Configuration

CPython has two configuration surfaces:

1. Build-time — controlled by ./configure flags, parsed in configure.ac, recorded in pyconfig.h.
2. Runtime — controlled by the PyConfig / PyPreConfig structs (Include/cpython/initconfig.h) and by environment variables / command-line flags interpreted in Python/initconfig.c and Python/preconfig.c.

Build-time flags

The full list is in ./configure --help. Frequently used:

Flag	Effect
--with-pydebug	Py_DEBUG. Asserts on, refcount checks, tracerefs.
--with-trace-refs	Track every live object (subset of pydebug; useful with PYTHONDUMPREFS).
--with-assertions	Keep assert even without full pydebug.
--enable-optimizations	PGO. Slow build, fastest binary.
--with-lto	Link-time optimisation.
--with-system-expat / --with-system-libmpdec / --with-system-libb2 / --with-system-mimalloc	Use the system copy of a vendored library instead of the in-tree one.
--with-openssl=DIR	Path to OpenSSL.
--with-ssl-default-suites=...	Override OpenSSL cipher list.
--with-tcltk-includes / --with-tcltk-libs	Tk paths.
--with-readline=editline / --with-readline=no	Choose readline, libedit, or none.
--enable-shared	Build libpython.so. Otherwise the interpreter is statically linked.
--with-tracing	Enable DTrace static probes (Include/pydtrace.d).
--enable-experimental-jit	Build the copy-and-patch JIT (JIT).
--enable-experimental-jit=interpreter	Use the uop interpreter instead of generating code.
--disable-gil	Free-threaded build (PEP 703).
--with-pystats	Enable Python/pystats.c counters.
--with-mimalloc=no	Disable bundled mimalloc.
--with-static-libpython=no	Don't ship libpython.a in the install.
--enable-loadable-sqlite-extensions	Build _sqlite3 with extension loading enabled.
--with-suffix=exe	Override the executable suffix.
--enable-framework=DIR (macOS)	Build a .framework install layout.
--with-platlibdir=lib	Override the lib directory name (used on Debian-style multilib).
--with-app-store-compliance	macOS App Store-friendly subset.
--with-emscripten-target=... / --with-wasi-target=...	Cross-compile for browser/WASI.

WASI / Emscripten / Android cross-builds have their own configuration recipes under Tools/wasm/, Mac/, Lib/_android_support.py.

PyConfig (runtime)

PyConfig is the embedder-facing replacement for the older Py_Set* functions. The full struct is in Include/cpython/initconfig.h; the parser is Python/initconfig.c (~138k lines, dominated by serialisation glue).

Highlights:

Field	Effect
parse_argv	Whether argv is parsed for Python flags.
optimization_level	Maps to -O / -OO.
bytes_warning	-b / -bb.
dev_mode	-X dev / PYTHONDEVMODE.
verbose	-v / PYTHONVERBOSE.
quiet	Suppress copyright/version banner.
interactive	-i / PYTHONINSPECT.
inspect	Drop into REPL after running the script.
isolated	-I (no per-user site-packages, no env vars).
safe_path	-P (don't prepend cwd / script dir to sys.path).
use_environment	Whether PYTHON* env vars are honored.
program_name, executable, prefix, exec_prefix, base_prefix, base_exec_prefix	Where Python "is".
home	PYTHONHOME.
module_search_paths	sys.path.
pythonpath_env	PYTHONPATH.
xoptions	-X foo=bar.
warnoptions	-W filter list.
tracemalloc	PYTHONTRACEMALLOC frame depth.
import_time	-X importtime.
show_alloc_count	Print allocation counts at exit (debug builds).
dump_refs / dump_refs_file	PYTHONDUMPREFS.
malloc_stats	PYTHONMALLOCSTATS.
filesystem_encoding / filesystem_errors	The filesystem codec.
stdio_encoding / stdio_errors	The stdin/stdout codec.
_install_importlib	Whether to install the import system (false for very stripped embeds).
_init_main	Whether to run __main__.

Embedders typically use:

PyConfig config;
PyConfig_InitPythonConfig(&config);
config.isolated = 1;
config.parse_argv = 0;
PyStatus status = Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

PyPreConfig (for Py_PreInitializeFromConfig) decides things that must be set before anything else, namely allocator selection (pymalloc / pymalloc_debug / malloc / malloc_debug) and locale coercion.

Environment variables

Variable	Effect
PYTHONHOME	Override sys.prefix / sys.exec_prefix.
PYTHONPATH	Prepend to sys.path.
PYTHONSTARTUP	Script to run at REPL start.
PYTHONOPTIMIZE	Maps to optimization_level.
PYTHONDEBUG	Parser debug.
PYTHONVERBOSE	Trace import.
PYTHONHASHSEED	Seed for hash randomization (0 disables).
PYTHONUTF8	Force UTF-8 mode.
PYTHONIOENCODING	stdin/stdout codec.
PYTHONNOUSERSITE	Don't add user site-packages to sys.path.
PYTHONDONTWRITEBYTECODE	Don't write .pyc.
PYTHONUNBUFFERED	Unbuffered stdout/stderr.
PYTHONDUMPREFS	Dump live objects on shutdown (debug build).
PYTHONMALLOC	Allocator selection (pymalloc, pymalloc_debug, malloc, malloc_debug).
PYTHONMALLOCSTATS	Print obmalloc stats on shutdown.
PYTHONFAULTHANDLER	Install fatal-signal traceback handler.
PYTHONTRACEMALLOC	Frames per allocation in tracemalloc.
PYTHONDEVMODE	Equivalent to -X dev.
PYTHONWARNINGS	Warning filter list.
PYTHONLEGACYWINDOWSFSENCODING	Use mbcs for filesystem on Windows.
PYTHONLEGACYWINDOWSSTDIO	Use ANSI stdio on Windows.
PYTHONNODEBUGRANGES	Skip per-instruction column ranges in tracebacks.
PYTHON_GIL	Force per-interpreter GIL on/off (free-threaded build).
PYTHON_HISTORY	History file for the new REPL.
PYTHON_BASIC_REPL	Use the old REPL.

The full list is in Doc/using/cmdline.rst.

-X options

-X foo=bar populates PyConfig.xoptions. Recognized by the runtime:

-X option	Effect
dev	Development mode (warnings, faulthandler).
tracemalloc	Equivalent to PYTHONTRACEMALLOC=1.
importtime	Print per-module import durations.
faulthandler	Same as PYTHONFAULTHANDLER.
frozen_modules=on/off	Force frozen-module use.
int_max_str_digits=N	Cap on int↔str conversion length (security mitigation, default 4300).
cpu_count=N	Override os.cpu_count.
pycache_prefix=DIR	Where to write .pyc caches.
showrefcount	Print refcount on REPL prompt.
gil=0/1	Force enable/disable GIL on a free-threaded build.
perf / perf_jit	Emit perf maps for perf record.
disable_remote_debug	Disable Python/remote_debugging.c attach point.