PyO3/pyo3 · error

PYO3_CROSS_LIB_DIR variable value is not a valid UTF-8 strin

Error message

PYO3_CROSS_LIB_DIR variable value is not a valid UTF-8 string

What it means

Error while converting the PYO3_CROSS_LIB_DIR environment variable to a PathBuf via into_path_buf: on this platform the variable's raw bytes are not valid UTF-8, and the build config requires paths to be UTF-8 representable before it can use the cross lib directory.

Source

Thrown at pyo3-build-config/src/impl_.rs:1788

                    .ok_or("PYO3_CROSS_PYTHON_IMPLEMENTATION is not valid a UTF-8 string")?;
                utf8_str
                    .parse()
                    .context("failed to parse PYO3_CROSS_PYTHON_IMPLEMENTATION")
            })
            .transpose()?;

        Ok(implementation)
    }

    /// Converts the stored `PYO3_CROSS_LIB_DIR` variable value (if any)
    /// into a `PathBuf` instance.
    ///
    /// Ensures that the path is a valid UTF-8 string.
    fn lib_dir_path(&self) -> Result<Option<PathBuf>> {
        let lib_dir = self.pyo3_cross_lib_dir.as_ref().map(PathBuf::from);

        if let Some(dir) = lib_dir.as_ref() {
            ensure!(
                dir.to_str().is_some(),
                "PYO3_CROSS_LIB_DIR variable value is not a valid UTF-8 string"
            );
        }

        Ok(lib_dir)
    }
}

/// Detect whether we are cross compiling and return an assembled CrossCompileConfig if so.
///
/// This function relies on PyO3 cross-compiling environment variables:
///
/// * `PYO3_CROSS`: If present, forces PyO3 to configure as a cross-compilation.
/// * `PYO3_CROSS_LIB_DIR`: If present, must be set to the directory containing
///   the target's libpython DSO and the associated `_sysconfigdata*.py` file for
///   Unix-like targets, or the Python DLL import libraries for the Windows target.
/// * `PYO3_CROSS_PYTHON_VERSION`: Major and minor version (e.g. 3.9) of the target Python

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Re-set PYO3_CROSS_LIB_DIR with a plain ASCII/UTF-8 path, avoiding locale-specific byte sequences
2. Quote the variable in CI scripts so it is not mangled by the shell
3. On Windows, avoid non-ANSI characters in the cross lib directory path

When it happens

Trigger: Thrown at pyo3-build-config/src/impl_.rs:1788 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of PyO3/pyo3@ac9b6899d3 (2026-09-05). Data as JSON: /api/errors/14c0c1f558ceb610. Report an issue: GitHub.