{"record":{"id":"ba934e06008d1138","repo":"PyO3/pyo3","slug":"failed-to-parse-pyo3-config","errorCode":null,"errorMessage":"failed to parse PyO3 config","messagePattern":"failed to parse PyO3 config","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pyo3-build-config/src/lib.rs","lineNumber":147,"sourceCode":"        }\n    }\n}\n\n/// Loads the configuration determined from the build environment.\n///\n/// This function must be called from a build script, and requires a direct dependency on at\n/// least one of `pyo3` or `pyo3-ffi`.\npub fn get() -> &'static InterpreterConfig {\n    static CONFIG: LazyLock<InterpreterConfig> = LazyLock::new(get_inner);\n    &CONFIG\n}\n\n#[track_caller]\nfn get_inner() -> InterpreterConfig {\n    let Some(interpreter_config) = InterpreterConfig::from_cargo_dep_env() else {\n        panic!(\"`pyo3_build_config::get()` requires a direct dependency on `pyo3` or `pyo3-ffi`\")\n    };\n    interpreter_config.expect(\"failed to parse PyO3 config\")\n}\n\n/// Registers `pyo3`s config names as reachable cfg expressions.\n///\n/// - <https://github.com/rust-lang/cargo/pull/13571>\n/// - <https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-check-cfg>\n#[doc(hidden)]\npub fn print_expected_cfgs() {\n    println!(\"cargo:rustc-check-cfg=cfg(Py_LIMITED_API)\");\n    println!(\"cargo:rustc-check-cfg=cfg(Py_GIL_DISABLED)\");\n    println!(\"cargo:rustc-check-cfg=cfg(PyPy)\");\n    println!(\"cargo:rustc-check-cfg=cfg(GraalPy)\");\n    println!(\"cargo:rustc-check-cfg=cfg(RustPython)\");\n    println!(\n        r#\"cargo:rustc-check-cfg=cfg(py_sys_config, values(\"Py_DEBUG\", \"Py_REF_DEBUG\", \"Py_TRACE_REFS\", \"COUNT_ALLOCS\"))\"#\n    );\n\n    // allow `Py_3_*` cfgs from the minimum supported version up to the","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/PyO3/pyo3/blob/ac9b6899d348be4d54614d060dea53a645a12e36/pyo3-build-config/src/lib.rs#L129-L165","documentation":"pyo3-build-config panics with this message when the collected PyO3 interpreter configuration (from cargo metadata / PYO3_* env vars / python detection) cannot be parsed into a valid InterpreterConfig during a build. It runs in the build-script phase, so the failure aborts compilation of any crate depending on pyo3 or pyo3-ffi.","triggerScenarios":"Calling pyo3_build_config::get() when InterpreterConfig::from_cargo_dep_env() returns an unparsable or malformed config — typically a corrupted or hand-edited config passed via the cargo dep env, or an invalid PYO3_CONFIG_FILE.","commonSituations":"Malformed PYO3_CONFIG_FILE, mismatched PYO3_PYTHON / cross-compilation env vars, stale cargo target caches after switching Python interpreters or pyo3 versions.","solutions":["Clear stale build artifacts: cargo clean, then rebuild so the build script re-detects Python","Check PYO3_CONFIG_FILE contents against the documented format (implementation, version, shared, pointer width, build flags)","Unset conflicting PYO3_* env vars (PYO3_PYTHON, PYO3_CONFIG_FILE) and let pyo3 auto-detect","Ensure a direct dependency on pyo3 or pyo3-ffi exists in Cargo.toml","Pin or update the pyo3 version to one compatible with your toolchain"],"exampleFix":"// before\nexport PYO3_CONFIG_FILE=my-custom-config  # hand-written, malformed\n// after\nunset PYO3_CONFIG_FILE\nexport PYO3_PYTHON=/usr/bin/python3.12\ncargo clean && cargo build","handlingStrategy":"validation","validationCode":"# in shell before building\nif [ -n \"$PYO3_CONFIG_FILE\" ]; then\n  cat \"$PYO3_CONFIG_FILE\"  # must match the documented 5+ line format\nfi\npython --version  # confirm the interpreter pyo3 will detect","typeGuard":null,"tryCatchPattern":"// build-time panic, not catchable in Rust; fix env and retry\ncargo clean && cargo build 2>&1 | grep -A5 'failed to parse PyO3 config'","preventionTips":["Never hand-write PYO3_CONFIG_FILE; generate it with pyo3-build-config tooling","Keep one canonical Python interpreter per build environment","Run cargo clean after switching Python or pyo3 versions","Audit PYO3_* env vars in CI before building"],"tags":["rust","build-script","pyo3","configuration"],"backgroundTag":"build-config-parse-failure","analyzedSha":"ac9b6899d348be4d54614d060dea53a645a12e36","analyzedAt":"2026-09-05T09:20:35.319Z","contentChangedAt":"2026-09-05T09:20:35.319Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}