{"record":{"id":"7941f04482bb098d","repo":"PyO3/pyo3","slug":"pyo3-config-file-must-be-an-absolute-path","errorCode":null,"errorMessage":"PYO3_CONFIG_FILE must be an absolute path","messagePattern":"PYO3_CONFIG_FILE must be an absolute path","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pyo3-build-config/src/impl_.rs","lineNumber":668,"sourceCode":"            .shared(shared || framework)\n            .pointer_width(pointer_width)\n            .lib_name(lib_name)\n            .lib_dir(lib_dir)\n            .python_framework_prefix(python_framework_prefix)\n            .build_flags(build_flags)\n            .finalize()\n    }\n\n    /// Import an externally-provided config file.\n    ///\n    /// The `abi3` features, if set, may apply an `abi3` constraint to the Python version.\n    pub(super) fn from_pyo3_config_file_env(target: &Triple) -> Option<Result<Self>> {\n        env_var(\"PYO3_CONFIG_FILE\").map(|path| {\n            let path = Path::new(&path);\n            println!(\"cargo:rerun-if-changed={}\", path.display());\n            // Absolute path is necessary because this build script is run with a cwd different to the\n            // original `cargo build` instruction.\n            ensure!(\n                path.is_absolute(),\n                \"PYO3_CONFIG_FILE must be an absolute path\"\n            );\n\n            let mut config = InterpreterConfig::from_path(path)\n                .context(\"failed to parse contents of PYO3_CONFIG_FILE\")?\n                .apply_build_env()?;\n\n            // For config files which don't apply a lib name, apply a default which we can use\n            // for linking.\n            if config.lib_name.is_none() {\n                config.lib_name = Some(default_lib_name_for_target(config.target_abi, target));\n            }\n\n            Ok(config)\n        })\n    }\n","sourceCodeStart":650,"sourceCodeEnd":686,"githubUrl":"https://github.com/PyO3/pyo3/blob/ac9b6899d348be4d54614d060dea53a645a12e36/pyo3-build-config/src/impl_.rs#L650-L686","documentation":"The PYO3_CONFIG_FILE environment variable lets users supply a hand-written interpreter config. Because the build script runs with a working directory different from where cargo was invoked, a relative path would resolve incorrectly, so pyo3 requires the value to be an absolute path and bails otherwise.","triggerScenarios":"Setting PYO3_CONFIG_FILE to a relative path (e.g. PYO3_CONFIG_FILE=./python-config or `interpreter.cfg`) before cargo build; from_pyo3_config_file_env calls path.is_absolute() and ensure! fails on false.","commonSituations":"Copy-pasting docs examples and forgetting to expand the path; CI scripts using paths relative to the repo root while cargo runs from a workspace member directory; Docker builds with WORKDIR changes.","solutions":["Set PYO3_CONFIG_FILE to an absolute path: `export PYO3_CONFIG_FILE=\"$PWD/pyo3-config.txt\"`","Generate the path in the build wrapper with an absolute resolver (realpath/readlink -f) before exporting","In CI, compute the absolute path from the repo root variable rather than using a relative literal"],"exampleFix":"# before\nexport PYO3_CONFIG_FILE=./pyo3-config.txt\ncargo build\n# after\nexport PYO3_CONFIG_FILE=\"$PWD/pyo3-config.txt\"\ncargo build","handlingStrategy":"validation","validationCode":"// shell\n[ -n \"$PYO3_CONFIG_FILE\" ] && [ \"$(readlink -f \"$PYO3_CONFIG_FILE\")\" = \"$PYO3_CONFIG_FILE\" ] || echo 'PYO3_CONFIG_FILE must be absolute'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always export PYO3_CONFIG_FILE with $PWD or an absolute base path","In CI, derive the path from GITHUB_WORKSPACE/CI_PROJECT_DIR","Run realpath on generated config paths before exporting"],"tags":["rust","pyo3","env-var","path","pyo3-config-file","build-time"],"backgroundTag":"relative-path-env-var","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"}