The sysconfig module exposes information about the current Python installation: standard-library directories, package destinations, headers, scripts, data paths, build variables, platform identifiers, installation schemes, and extension suffixes. It is useful for build tools, installers, environment diagnostics, packaging systems, and native-code integration.
Ordinary applications rarely need to construct installation paths manually. Use importlib to locate imported modules, importlib.resources for package data, and packaging tools to install dependencies. sysconfig is appropriate when the task is specifically to understand or automate details of the Python installation itself.
The current runtime
Results describe the interpreter running the script. This matters when a machine has several Python installations, virtual environments, debug builds, system packages, and custom distributions.
import sys
import sysconfig
print(sys.executable)
print(sysconfig.get_platform())
print(sysconfig.get_python_version())
Record the executable path with diagnostics to avoid inspecting the wrong environment.
Installation schemes
An installation scheme is a named collection of path templates for different file categories.
import sysconfig
print(sysconfig.get_scheme_names())
Available names vary across platforms and distributions. Do not hard-code one universal list.
Path categories
get_path_names() reports categories such as stdlib, platstdlib, purelib, platlib, include, platinclude, scripts, and data.
print(sysconfig.get_path_names())
Several categories may resolve to the same directory in a particular installation.
stdlib and platstdlib
stdlib identifies the standard-library destination that is independent of platform-specific extension layout. platstdlib represents platform-dependent standard-library content.
Do not modify those directories at runtime. System installations may be read-only or managed by an operating-system package manager.
purelib and platlib
purelib is the usual destination for pure Python packages. platlib is used for packages containing platform-dependent components.
print(sysconfig.get_path("purelib"))
print(sysconfig.get_path("platlib"))
The values may be identical on one installation and different on another.
include and platinclude
These categories locate headers needed to compile C extensions or embed Python.
include = sysconfig.get_path("include")
platform_include = sysconfig.get_path("platinclude")
A build tool should verify that the directories exist. Some systems require a separate development package.
scripts
The scripts path indicates where command-line entry points are installed for a scheme.
Do not automatically alter a user’s PATH without consent. Report the location and provide clear instructions.
data
The data category is a base for general installation data under the selected scheme.
Do not use it to locate resources inside an imported package. importlib.resources is designed for that purpose.
get_paths
get_paths() returns every expanded path for a scheme.
paths = sysconfig.get_paths()
for name, path in sorted(paths.items()):
print(f"{name}: {path}")
The result is useful for diagnostics and builds, but it does not guarantee that every directory exists or is writable.
Select a scheme
Path functions accept an explicit scheme name.
paths = sysconfig.get_paths(scheme="posix_prefix")
Check get_scheme_names() first. A POSIX-specific name is not portable to Windows.
Template variables
Path templates are expanded with configuration variables. A custom vars mapping can simulate another prefix.
paths = sysconfig.get_paths(
vars={"base": "/opt/app", "platbase": "/opt/app"}
)
A simulated result is not necessarily a valid install. Use packaging tools for actual installation.
get_path
get_path(name) is convenient when only one category is needed.
scripts_directory = sysconfig.get_path("scripts")
Validate names and handle differences across Python versions.
Configuration variables
get_config_vars() returns values used to configure and build the interpreter.
variables = sysconfig.get_config_vars()
print(variables.get("CC"))
print(variables.get("CFLAGS"))
print(variables.get("EXT_SUFFIX"))
Values are installation-specific and can be strings, numbers, or None.
get_config_var
Use get_config_var(name) for one variable.
suffix = sysconfig.get_config_var("EXT_SUFFIX")
Do not assume every variable exists on every platform. Handle None.
Compiler and flags
Variables such as CC, CXX, CFLAGS, LDFLAGS, and library names help native build tools reproduce compatible settings.
Do not concatenate these strings with untrusted input and pass the result to a shell. Parse deliberately and invoke subprocesses with argument lists.
EXT_SUFFIX
EXT_SUFFIX reports the expected filename suffix for compiled extension modules.
print(sysconfig.get_config_var("EXT_SUFFIX"))
The value can include ABI, architecture, and shared-library details. Never replace it with a fixed .so or .pyd.
SOABI
SOABI identifies ABI-related information used in extension names.
Matching SOABI alone does not prove full compatibility. Operating system, architecture, external libraries, and runtime build also matter.
Shared-library variables
Build variables can indicate whether Python uses a shared library and how that library is named.
Custom distributions may change these values. Test embedding and linking on the real target system.
get_platform
get_platform() returns a platform string used by build and packaging contexts.
platform_tag = sysconfig.get_platform()
It is not a security identity and should not replace capability detection. Test the feature you need.
get_python_version
The function returns the short major.minor version used in installation paths.
For full runtime details, combine it with sys.version_info and platform.python_implementation().
Virtual environments
Inside a virtual environment, several installation paths refer to the environment while build information still comes from the underlying interpreter.
import sys
print(sys.prefix)
print(sys.base_prefix)
Test in a real venv. Do not assume every path begins with sys.prefix.
System installations
Linux distributions may customize schemes to cooperate with their package managers. Writing manually into system locations can damage the environment.
Use virtual environments or the distribution’s recommended installation method.
Windows
Windows schemes differ from POSIX. Script layout, extension suffixes, and ABI tags follow Windows conventions.
Test paths containing spaces and Unicode. Pass compiler arguments as a list.
macOS
Framework builds, universal binaries, and architecture differences can affect paths and flags.
Do not copy configuration from an Intel machine to Apple Silicon or the reverse without validation.
Cross compilation
sysconfig primarily describes the Python that is executing. During cross compilation, the host and target differ.
Use target-specific configuration files and the project’s build toolchain. Host values are not automatically valid for the target.
Diagnostic output
The module can be executed from the command line to display installation information, depending on the Python version.
A support report should include the executable, relevant sysconfig output, and packaging-tool version without exposing environment secrets.
Modern packaging
Build backends and installers already use the appropriate abstractions. Applications should not copy files directly into purelib.
Use pyproject.toml, wheels, and supported installers. sysconfig is an information source, not a packaging replacement.
C extension builds
A native build can query include paths and flags, but should generally rely on setuptools, Meson, CMake, or the selected backend.
This improves wheel generation and build isolation.
Permissions
A returned path may be read-only. Check permissions before writing and do not request elevation automatically.
A permission failure should recommend a virtual environment, not chmod 777.
Path handling
Convert returned text to pathlib.Path when performing filesystem operations.
from pathlib import Path
include = Path(sysconfig.get_path("include"))
if not include.is_dir():
raise RuntimeError("Python headers were not found")
Do not resolve symlinks unless necessary; installation layouts may intentionally use them.
Caching results
Values are normally stable for the lifetime of a process. A tool may cache them locally, but the cache must not be reused for another interpreter.
Include sys.executable and the Python version in the cache key.
Security
Compiler commands and flags come from the installation configuration. In a compromised environment, they can point to unexpected executables.
Build tools should run in isolation, record commands, and never combine configuration strings with hostile shell input.
Testing
Test Windows, Linux, and macOS; virtual and global installations; debug builds where relevant; paths with spaces; missing headers; and read-only directories.
Avoid assertions containing fixed absolute paths. Verify categories and properties instead.
Common mistakes
Common failures include hard-coding site-packages, confusing purelib and platlib, assuming every directory exists, writing into system Python, using host values for cross compilation, fixing extension names to .so, ignoring venv behavior, and executing flags through a shell without parsing.
Conclusion
sysconfig is the authoritative source for paths, schemes, and build variables of the current Python runtime. Use it for diagnostics and native integration while accounting for platform, virtual environments, permissions, and compatibility.
Use packaging tools rather than copying files manually. Consult the official sysconfig documentation and Python contextlib for resource management in build tools.
