Wrong wheel name when cross compiling with zig

[dreamtalen]

When cross-compiling a mixed Python/Rust project to aarch64-unknown-linux-gnu using maturin build --release --target aarch64-unknown-linux-gnu --zig, the resulting wheel file is tagged with the build host's architecture (linux_x86_64) instead of the target architecture (aarch64).

The actual compiled shared object (.so) inside the wheel is correctly compiled for aarch64-unknown-linux-gnu (as confirmed by verbose logs). The issue is specific to the platform tag in the wheel's filename and maybe other internal metadata.

(nix:nix-shell-env) yongmingd@ymding-vm-xl:~/multi-storage-client$ uv run maturin build --release --target aarch64-unknown-linux-gnu --zig
Uninstalled 1 package in 0.74ms
Installed 1 package in 9ms
📦 Including license file "/home/yongmingd/multi-storage-client/LICENSE"
🍹 Building a mixed python/rust project
🔗 Found pyo3 bindings with abi3 support for Python ≥ 3.9
🐍 Not using a specific python interpreter
📡 Using build options features from pyproject.toml
🛠️ Using zig for cross-compiling to aarch64-unknown-linux-gnu
   Compiling pyo3-build-config v0.24.2
   Compiling pyo3-ffi v0.24.2
   Compiling pyo3-macros-backend v0.24.2
   Compiling pyo3 v0.24.2
   Compiling pyo3-macros v0.24.2
   Compiling pyo3-async-runtimes v0.24.0
   Compiling msc_rustclient v0.1.0 (/home/yongmingd/multi-storage-client/rust)
    Finished `release` profile [optimized] target(s) in 12.91s
📦 Built wheel for abi3 Python ≥ 3.9 to /home/yongmingd/multi-storage-client/rust/target/wheels/multi_storage_client-0.20.2-cp39-abi3-linux_x86_64.whl

Environment:
* Build Host OS: Linux (x86_64 in my case)
* Target: aarch64-unknown-linux-gnu
* Maturin Version: 1.8.x
* Python for abi3 compatibility: >=3.9
* pyo3 bindings

When enabling on -vv, it shows packaging the correct .so file (from aarch64 target directory):
2025-05-08T22:30:18.938810Z DEBUG build_wheels:write_bindings_module: maturin::module_writer: Adding msc_rustclient/msc_rustclient.abi3.so from /home/yongmingd/multi-storage-client/rust/target/aarch64-unknown-linux-gnu/release/maturin/libmsc_rustclient.so

but generate incorrectly tagged final wheel:
📦 Built wheel for abi3 Python ≥ 3.9 to /home/yongmingd/multi-storage-client/rust/target/wheels/multi_storage_client-0.20.2-cp39-abi3-linux_x86_64.whl

Thanks for your help!

[messense]

Could you create a repro process without using nix like in a Docker container?

[dreamtalen]

Thanks for your reply @messense! I tried a Docker container and was unable to reproduce the original issue (generated wheel was correctly named)

Given this, this may not be something directly to Maturin but specific to my Nix environment.
Do you have any insights into potential interactions between Maturin's wheel tagging logic and a Nix environment that might cause it to pick up the host's platform tag despite the cross-compilation target? For instance, could certain environment variables influence Maturin's defaults in this scenario? Thanks!

[commiterate]

• maturin/src/build_context.rs

  Lines 685 to 694 in 9661718

  	let (wheel_path, tag) =
  	self.write_pyo3_wheel_abi3(artifact, &platform_tags, external_libs, major, min_minor)?;
  	eprintln!(
  	"📦 Built wheel for abi3 Python ≥ {}.{} to {}",
  	major,
  	min_minor,
  	wheel_path.display()
  	);
  	wheels.push((wheel_path, tag));

• maturin/src/build_context.rs

  Lines 619 to 628 in 9661718

  	fn write_pyo3_wheel_abi3(
  	&self,
  	artifact: BuildArtifact,
  	platform_tags: &[PlatformTag],
  	ext_libs: Vec<Library>,
  	major: u8,
  	min_minor: u8,
  	) -> Result<BuiltWheelMetadata> {
  	let platform = self.get_platform_tag(platform_tags)?;
  	let tag = format!("cp{major}{min_minor}-abi3-{platform}");

• maturin/src/build_context.rs

  Lines 486 to 489 in 9661718

  	pub fn get_platform_tag(&self, platform_tags: &[PlatformTag]) -> Result<String> {
  	if let Ok(host_platform) = env::var("_PYTHON_HOST_PLATFORM") {
  	return Ok(host_platform.replace(['.', '-'], "_"));
  	}

• https://github.com/NixOS/nixpkgs/blob/dda3dcd3fe03e991015e9a74b22d35950f264a54/pkgs/development/interpreters/python/cpython/default.nix#L704-L731

This is an artifact of how Maturin's platform resolution chain works:

1. Check for the _PYTHON_HOST_PLATFORM environment variable.
2. Use the supplied --target.

_PYTHON_HOST_PLATFORM needs to be unset (e.g. env --unset _PYTHON_HOST_PLATFORM maturin build --target {platform}) so the supplied --target is used instead.

I think this is a bug on Maturin's side since it breaks cross-compilation in environments where _PYTHON_HOST_PLATFORM is set.

Maturin should probably use the host platform as a fallback if --target is omitted. Any dependent logic should just rely on the target it's given instead of trying to guess from environment variables and other stuff.

[messense]

The env var has to take precedence over --target because _PYTHON_HOST_PLATFORM is not the same thing as --target.

For example given an iOS Rust target aarch64-apple-ios, the iOS Python wheel platform tag could be ios_12_0_arm64_iphoneos which includes additional version information that is not included in --target.

[messense]

I'd argue Nix should not set _PYTHON_HOST_PLATFORM, it should modify _sysconfigdata_*.py file instead. _PYTHON_HOST_PLATFORM is used in the wild for customizing the platform tags to whatever the user wants due to reasons: https://www.google.com/search?q=_PYTHON_HOST_PLATFORM

[commiterate]

Created an issue in Nixpkgs to get more context around the the postFixup hook on the python Nix package.

NixOS/nixpkgs#406020

I think it has to do with cross-compiling if using Nix as the build system, which unfortunately impacts cross-compiling if using Nix strictly for a build shell (not as the build system).

[commiterate]

On the Maturin side (or for Python in general), is there a valid use case for having a wheel be named after the host platform but its contents to have compiled objects for a different target platform?

[messense]

I don't think there is a valid use case, _PYTHON_HOST_PLATFORM is currently an escape hatch, we can certainly add some validations to it to avoid mistakes.