Python Basics: Inspect Installation Schemes with sysconfig

Hard-coded library paths break across interpreters, platforms, and virtual environments. sysconfig describes installation schemes and build configuration. Start by inspecting the available path roles, then expand a scheme against a clearly artificial prefix.

Prepare a scratch directory

Tested on Linux with CPython 3.12.14. You need the named runtime, Bash, a text editor, and the standard mktemp, rm, and rmdir utilities. Run Python without -O so the assertions remain enabled. Any generated fixture files live inside an automatically cleaned temporary directory.

Keep using the same terminal. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-sysconfig.py:

import sysconfig

paths = sysconfig.get_paths()
required = {"stdlib", "purelib", "platlib", "scripts", "include"}
assert required <= paths.keys()
assert all(isinstance(paths[key], str) and paths[key] for key in required)
print("Required path roles:", ", ".join(sorted(required)))

variables = {"base": "/example-prefix", "platbase": "/example-prefix"}
preview = sysconfig.get_paths(scheme="posix_prefix", vars=variables)
assert preview["scripts"] == "/example-prefix/bin"
print("Preview scripts:", preview["scripts"])
print("Pure-Python library uses preview prefix:",
      preview["purelib"].startswith("/example-prefix/"))
assert preview["purelib"].startswith("/example-prefix/")
unknown = sysconfig.get_config_var("EXAMPLE_OPTION_THAT_DOES_NOT_EXIST")
assert unknown is None
print("Unknown build variable:", unknown)

Run it:

python3 -B demonstrate-sysconfig.py

Observed output:

Required path roles: include, platlib, purelib, scripts, stdlib
Preview scripts: /example-prefix/bin
Pure-Python library uses preview prefix: True
Unknown build variable: None

Read the result

The first check asks for meaningful path roles without printing machine-specific absolute paths. posix_prefix is an explicit POSIX scheme; overriding base and platbase previews selected paths under a fictitious prefix. This is only string expansion: the script creates no directory and installs no package. Missing configuration variables return None, which callers should handle instead of assuming every build exposes every option.

Apply it carefully

The default scheme can differ inside a virtual environment and can be customized by distributors. Prefer packaging tools for installation rather than copying into purelib yourself. This Linux example does not claim that every path in the preview uses the replacement prefix; other scheme roles can use other variables. Build configuration describes the interpreter build, not a guarantee that headers or a compiler are installed on the current machine.

The official reference describes the API and its options. The checks above cover the specific fixture, not every possible input or environment.

Clean up

Remove the source and then the empty practice directory:

rm -- demonstrate-sysconfig.py
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect the remaining files rather than deleting unknown contents.

Acknowledgements

This post was created with assistance from AI.