PyInitConfig C API
Added in version 3.14.
Python can be initialized with
.
The
function can be used to write a customized Python program.
See also
Initialization, Finalization, and Threads
.
See also
“Python Configuration C API”.
Example
Example of customized Python always running with the
enabled; return -1 on error:
intinit_python(void){PyInitConfig*config=PyInitConfig_Create();if(config==NULL){printf("PYTHON INIT ERROR: memory allocation failed\n");return-1;}// Enable the Python Development Modeif(PyInitConfig_SetInt(config,"dev_mode",1)<0){gotoerror;}// Initialize Python with the configurationif(Py_InitializeFromInitConfig(config)<0){gotoerror;}PyInitConfig_Free(config);return0;error:{// Display the error message.//// This uncommon braces style is used, because you cannot make// goto targets point to variable declarations.constchar*err_msg;(void)PyInitConfig_GetError(config,&err_msg);printf("PYTHON INIT ERROR: %s\n",err_msg);PyInitConfig_Free(config);return-1;}}Create Config
structPyInitConfig
Opaque structure to configure the Python initialization.
*PyInitConfig_Create(void)
Create a new initialization configuration using
default values.
It must be freed by
.
Return NULL on memory allocation failure.
voidPyInitConfig_Free(
*config)
Free memory of the initialization configuration config.
If config is NULL, no operation is performed.
Error Handling
intPyInitConfig_GetError(
*config, constchar**err_msg)
Get the config error message.
Set *err_msg and return 1 if an error is set.
Set *err_msg to NULL and return 0 otherwise.
An error message is a UTF-8 encoded string.
If config has an exit code, format the exit code as an error message.
The error message remains valid until another PyInitConfig function is called with config. The caller doesn’t have to free the error message.
intPyInitConfig_GetExitCode(
*config, int*exitcode)
Get the config exit code.
Set *exitcode and return 1 if config has an exit code set.
Return 0 if config has no exit code set.
Only the Py_InitializeFromInitConfig() function can set an exit code if the parse_argv option is non-zero.
An exit code can be set when parsing the command line failed (exit code 2) or when a command line option asks to display the command line help (exit code 0).
Get Options
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See
.
intPyInitConfig_HasOption(
*config, constchar*name)
Test if the configuration has an option called name.
Return 1 if the option exists, or return 0 otherwise.
intPyInitConfig_GetInt(
*config, constchar*name, int64_t*value)
Get an integer configuration option.
Set *value, and return 0 on success.
Set an error in config and return -1 on error.
intPyInitConfig_GetStr(
*config, constchar*name, char**value)
Get a string configuration option as a null-terminated UTF-8 encoded string.
Set *value, and return 0 on success.
Set an error in config and return -1 on error.
*value can be set to NULL if the option is an optional string and the option is unset.
On success, the string must be released with free(value) if it’s not NULL.
intPyInitConfig_GetStrList(
*config, constchar*name, size_t*length, char***items)
Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.
Set *length and *value, and return 0 on success.
Set an error in config and return -1 on error.
On success, the string list must be released with PyInitConfig_FreeStrList(length,items).
voidPyInitConfig_FreeStrList(size_tlength, char**items)
Free memory of a string list created by PyInitConfig_GetStrList().
Set Options
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See
.
Some configuration options have side effects on other options. This logic is only implemented when Py_InitializeFromInitConfig() is called, not by the “Set” functions below. For example, setting dev_mode to 1 does not set faulthandler to 1.
intPyInitConfig_SetInt(
*config, constchar*name, int64_tvalue)
Set an integer configuration option.
Return 0 on success.
Set an error in config and return -1 on error.
intPyInitConfig_SetStr(
*config, constchar*name, constchar*value)
Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.
Return 0 on success.
Set an error in config and return -1 on error.
intPyInitConfig_SetStrList(
*config, constchar*name, size_tlength, char*const*items)
Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.
Return 0 on success.
Set an error in config and return -1 on error.
Module
intPyInitConfig_AddModule(
*config, constchar*name,
*(*initfunc)(void))
Add a built-in extension module to the table of built-in modules.
The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import.
Return 0 on success.
Set an error in config and return -1 on error.
If Python is initialized multiple times, PyInitConfig_AddModule() must be called at each Python initialization.
Similar to the
function.
Initialize Python
intPy_InitializeFromInitConfig(
*config)
Initialize Python from the initialization configuration.
Return 0 on success.
Set an error in config and return -1 on error.
Set an exit code in config and return -1 if Python wants to exit.
See PyInitConfig_GetExitcode() for the exit code case.
Configuration Options
Option
PyConfig/PyPreConfig member
Type
Visibility
"allocator"
int
Read-only
"argv"
list[str]
Public
"base_exec_prefix"
str
Public
"base_executable"
str
Public
"base_prefix"
str
Public
"buffered_stdio"
bool
Read-only
"bytes_warning"
int
Public
"check_hash_pycs_mode"
str
Read-only
"code_debug_ranges"
bool
Read-only
"coerce_c_locale"
bool
Read-only
"coerce_c_locale_warn"
bool
Read-only
"configure_c_stdio"
bool
Read-only
"configure_locale"
bool
Read-only
"cpu_count"
int
Public
"dev_mode"
bool
Read-only
"dump_refs"
bool
Read-only
"dump_refs_file"
str
Read-only
"exec_prefix"
str
Public
"executable"
str
Public
"faulthandler"
bool
Read-only
"filesystem_encoding"
str
Read-only
"filesystem_errors"
str
Read-only
"hash_seed"
int
Read-only
"home"
str
Read-only
"import_time"
int
Read-only
"inspect"
bool
Public
"install_signal_handlers"
bool
Read-only
"int_max_str_digits"
int
Public
"interactive"
bool
Public
"isolated"
bool
Read-only
"legacy_windows_fs_encoding"
bool
Read-only
"legacy_windows_stdio"
bool
Read-only
"malloc_stats"
bool
Read-only
"module_search_paths"
list[str]
Public
"optimization_level"
int
Public
"orig_argv"
list[str]
Read-only
"parse_argv"
bool
Read-only
"parser_debug"
bool
Public
"pathconfig_warnings"
bool
Read-only
"perf_profiling"
bool
Read-only
"platlibdir"
str
Public
"prefix"
str
Public
"program_name"
str
Read-only
"pycache_prefix"
str
Public
"quiet"
bool
Public
"run_command"
str
Read-only
"run_filename"
str
Read-only
"run_module"
str
Read-only
"run_presite"
str
Read-only
"safe_path"
bool
Read-only
"show_ref_count"
bool
Read-only
"site_import"
bool
Read-only
"skip_source_first_line"
bool
Read-only
"stdio_encoding"
str
Read-only
"stdio_errors"
str
Read-only
"stdlib_dir"
str
Public
"tracemalloc"
int
Read-only
"use_environment"
bool
Public
"use_frozen_modules"
bool
Read-only
"use_hash_seed"
bool
Read-only
"use_system_logger"
bool
Read-only
"user_site_directory"
bool
Read-only
"utf8_mode"
bool
Read-only
"verbose"
int
Public
"warn_default_encoding"
bool
Read-only
"warnoptions"
list[str]
Public
"write_bytecode"
bool
Public
"xoptions"
dict[str,str]
Public
"_pystats"
bool
Read-only
Visibility:
Public: Can be retrieved by
and set by
.
Read-only: Can be retrieved by
, but cannot be set by
.
Runtime Python configuration API
At runtime, it’s possible to get and set configuration options using
and
functions.
The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string. See
.
Some options are read from the
attributes. For example, the option "argv" is read from
.
*PyConfig_Get(constchar*name)
Get the current runtime value of a configuration option as a Python object.
Return a new reference on success.
Set an exception and return NULL on error.
The object type depends on the configuration option. It can be:
bool
int
str
list[str]
dict[str,str]
The caller must have an
. The function cannot be called before Python initialization nor after Python finalization.
Added in version 3.14.
intPyConfig_GetInt(constchar*name, int*value)
Similar to
, but get the value as a C int.
Return 0 on success.
Set an exception and return -1 on error.
Added in version 3.14.
*PyConfig_Names(void)
Get all configuration option names as a frozenset.
Return a new reference on success.
Set an exception and return NULL on error.
The caller must have an
. The function cannot be called before Python initialization nor after Python finalization.
Added in version 3.14.
intPyConfig_Set(constchar*name,
*value)
Set the current runtime value of a configuration option.
Raise a
if there is no option name.
Raise a
if value is an invalid value.
Raise a
if the option is read-only (cannot be set).
Raise a
if value has not the proper type.
The caller must have an
. The function cannot be called before Python initialization nor after Python finalization.
Raises an
cpython.PyConfig_Set with arguments name, value.
Added in version 3.14.
Changed in version 3.14.7: The function now replaces
(create a new object), instead of modifying sys.flags in-place.
PyConfig C API
Added in version 3.8.
Python can be initialized with
and the
structure. It can be preinitialized with
and the
structure.
There are two kinds of configuration:
The
can be used to build a customized Python which behaves as the regular Python. For example, environment variables and command line arguments are used to configure Python.
The
can be used to embed Python into an application. It isolates Python from the system. For example, environment variables are ignored, the LC_CTYPE locale is left unchanged and no signal handler is registered.
The
function can be used to write a customized Python program.
See also
Initialization, Finalization, and Threads
.
See also
“Python Initialization Configuration”.
Example
Example of customized Python always running in isolated mode:
intmain(intargc,char**argv){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);config.isolated=1;/* Decode command line arguments. Implicitly preinitialize Python (in isolated mode). */status=PyConfig_SetBytesArgv(&config,argc,argv);if(PyStatus_Exception(status)){gotoexception;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotoexception;}PyConfig_Clear(&config);returnPy_RunMain();exception:PyConfig_Clear(&config);if(PyStatus_IsExit(status)){returnstatus.exitcode;}/* Display the error message and exit the process with non-zero exit code */Py_ExitStatusException(status);}PyWideStringList
typePyWideStringList
List of wchar_t* strings.
If length is non-zero, items must be non-NULL and all strings must be non-NULL.
Methods:
PyWideStringList_Append(
*list, constwchar_t*item)
Append item to list.
Python must be preinitialized to call this function.
PyWideStringList_Insert(
*list,
index, constwchar_t*item)
Insert item into list at index.
If index is greater than or equal to list length, append item to list.
index must be greater than or equal to 0.
Python must be preinitialized to call this function.
Structure fields:
length
List length.
wchar_t**items
List items.
PyStatus
typePyStatus
Structure to store an initialization function status: success, error or exit.
For an error, it can store the C function name which created the error.
Structure fields:
intexitcode
Exit code. Argument passed to exit().
constchar*err_msg
Error message.
constchar*func
Name of the function which created an error, can be NULL.
Functions to create a status:
PyStatus_Ok(void)
Success.
PyStatus_Error(constchar*err_msg)
Initialization error with a message.
err_msg must not be NULL.
PyStatus_NoMemory(void)
Memory allocation failure (out of memory).
PyStatus_Exit(intexitcode)
Exit Python with the specified exit code.
Functions to handle a status:
intPyStatus_Exception(
status)
Is the status an error or an exit? If true, the exception must be handled; by calling
for example.
intPyStatus_IsError(
status)
Is the result an error?
intPyStatus_IsExit(
status)
Is the result an exit?
voidPy_ExitStatusException(
status)
Call exit(exitcode) if status is an exit. Print the error message and exit with a non-zero exit code if status is an error. Must only be called if PyStatus_Exception(status) is non-zero.
Note
Internally, Python uses macros which set PyStatus.func, whereas functions to create a status set func to NULL.
Example:
PyStatusalloc(void**ptr,size_tsize){*ptr=PyMem_RawMalloc(size);if(*ptr==NULL){returnPyStatus_NoMemory();}returnPyStatus_Ok();}intmain(intargc,char**argv){void*ptr;PyStatusstatus=alloc(&ptr,16);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}PyMem_Free(ptr);return0;}PyPreConfig
typePyPreConfig
Structure used to preinitialize Python.
Function to initialize a preconfiguration:
voidPyPreConfig_InitPythonConfig(
*preconfig)
Initialize the preconfiguration with
.
voidPyPreConfig_InitIsolatedConfig(
*preconfig)
Initialize the preconfiguration with
.
Structure fields:
intallocator
Name of the Python memory allocators:
PYMEM_ALLOCATOR_NOT_SET (0): don’t change memory allocators (use defaults).
PYMEM_ALLOCATOR_DEFAULT (1):
.
PYMEM_ALLOCATOR_DEBUG (2):
with
.
PYMEM_ALLOCATOR_MALLOC (3): use malloc() of the C library.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage of malloc() with
.
PYMEM_ALLOCATOR_PYMALLOC (5):
Python pymalloc memory allocator
.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6):
Python pymalloc memory allocator
with
.
PYMEM_ALLOCATOR_MIMALLOC (6): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): use mimalloc, a fast malloc replacement with
.
PYMEM_ALLOCATOR_PYMALLOC and PYMEM_ALLOCATOR_PYMALLOC_DEBUG are not supported if Python is
configured using --without-pymalloc
.
PYMEM_ALLOCATOR_MIMALLOC and PYMEM_ALLOCATOR_MIMALLOC_DEBUG are not supported if Python is
configured using --without-mimalloc
or if the underlying atomic support isn’t available.
See
.
Default: PYMEM_ALLOCATOR_NOT_SET.
intconfigure_locale
Set the LC_CTYPE locale to the user preferred locale.
If equals to 0, set
and
members to 0.
See the
.
Default: 1 in Python config, 0 in isolated config.
intcoerce_c_locale
If equals to 2, coerce the C locale.
If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.
See the
.
Default: -1 in Python config, 0 in isolated config.
intcoerce_c_locale_warn
If non-zero, emit a warning if the C locale is coerced.
Default: -1 in Python config, 0 in isolated config.
intdev_mode
: see
.
Default: -1 in Python mode, 0 in isolated mode.
intisolated
Isolated mode: see
.
Default: 0 in Python mode, 1 in isolated mode.
intlegacy_windows_fs_encoding
If non-zero:
Set
to 0,
Set
to "mbcs",
Set
to "replace".
Initialized from the
environment variable value.
Only available on Windows. #ifdefMS_WINDOWS macro can be used for Windows specific code.
Default: 0.
intparse_argv
If non-zero,
and
Py_PreInitializeFromBytesArgs()
parse their argv argument the same way the regular Python parses command line arguments: see
.
Default: 1 in Python config, 0 in isolated config.
intuse_environment
Use
? See
.
Default: 1 in Python config and 0 in isolated config.
intutf8_mode
If non-zero, enable the
.
Set to 0 or 1 by the
command line option and the
environment variable.
Also set to 1 if the LC_CTYPE locale is C or POSIX.
Default: -1 in Python config and 0 in isolated config.
Preinitialize Python with PyPreConfig
The preinitialization of Python:
Set the Python memory allocators (
)
Configure the LC_CTYPE locale (
)
Set the
(
)
The current preconfiguration (PyPreConfig type) is stored in _PyRuntime.preconfig.
Functions to preinitialize Python:
Py_PreInitialize(const
*preconfig)
Preinitialize Python from preconfig preconfiguration.
preconfig must not be NULL.
Py_PreInitializeFromBytesArgs(const
*preconfig, intargc, char*const*argv)
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (bytes strings) if
of preconfig is non-zero.
preconfig must not be NULL.
Py_PreInitializeFromArgs(const
*preconfig, intargc, wchar_t*const*argv)
Preinitialize Python from preconfig preconfiguration.
Parse argv command line arguments (wide strings) if
of preconfig is non-zero.
preconfig must not be NULL.
The caller is responsible to handle exceptions (error or exit) using
and
.
For
(
PyPreConfig_InitPythonConfig()
), if Python is initialized with command line arguments, the command line arguments must also be passed to preinitialize Python, since they have an effect on the pre-configuration like encodings. For example, the
command line option enables the
.
PyMem_SetAllocator() can be called after
and before
to install a custom memory allocator. It can be called before Py_PreInitialize() if
is set to PYMEM_ALLOCATOR_NOT_SET.
Python memory allocation functions like
must not be used before the Python preinitialization, whereas calling directly malloc() and free() is always safe.
must not be called before the Python preinitialization.
Example using the preinitialization to enable the
:
PyStatusstatus;PyPreConfigpreconfig;PyPreConfig_InitPythonConfig(&preconfig);preconfig.utf8_mode=1;status=Py_PreInitialize(&preconfig);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}/* at this point, Python speaks UTF-8 */Py_Initialize();/* ... use Python API here ... */Py_Finalize();PyConfig
typePyConfig
Structure containing most parameters to configure Python.
When done, the
function must be used to release the configuration memory.
Structure methods:
voidPyConfig_InitPythonConfig(
*config)
Initialize configuration with the
.
voidPyConfig_InitIsolatedConfig(
*config)
Initialize configuration with the
.
PyConfig_SetString(
*config, wchar_t*const*config_str, constwchar_t*str)
Copy the wide character string str into *config_str.
if needed.
PyConfig_SetBytesString(
*config, wchar_t*const*config_str, constchar*str)
Decode str using
and set the result into *config_str.
if needed.
PyConfig_SetArgv(
*config, intargc, wchar_t*const*argv)
Set command line arguments (
member of config) from the argv list of wide character strings.
if needed.
PyConfig_SetBytesArgv(
*config, intargc, char*const*argv)
Set command line arguments (
member of config) from the argv list of bytes strings. Decode bytes using
.
if needed.
PyConfig_SetWideStringList(
*config,
*list,
length, wchar_t**items)
Set the list of wide strings list to length and items.
if needed.
PyConfig_Read(
*config)
Read all Python configuration.
Fields which are already initialized are left unchanged.
Fields for
are no longer calculated or modified when calling this function, as of Python 3.11.
The
function only parses
arguments once:
is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.
if needed.
Changed in version 3.10: The
arguments are now only parsed once,
is set to 2 after arguments are parsed, and arguments are only parsed if PyConfig.parse_argv equals 1.
Changed in version 3.11:
no longer calculates all paths, and so fields listed under
may no longer be updated until
is called.
voidPyConfig_Clear(
*config)
Release configuration memory.
Most PyConfig methods
if needed. In that case, the Python preinitialization configuration (
) is based on the
. If configuration fields which are in common with PyPreConfig are tuned, they must be set before calling a PyConfig method:
Moreover, if
or
is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if
is non-zero).
The caller of these methods is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().
Structure fields:
argv
Set
command line arguments based on
. These parameters are similar to those passed to the program’s main() function with the difference that the first entry should refer to the script file to be executed rather than the executable hosting the Python interpreter. If there isn’t a script that will be run, the first entry in argv can be an empty string.
Set
to 1 to parse
the same way the regular Python parses Python command line arguments and then to strip Python arguments from argv.
If
is empty, an empty string is added to ensure that
always exists and is never empty.
Default: NULL.
See also the
member.
intsafe_path
If equals to zero, Py_RunMain() prepends a potentially unsafe path to
at startup:
If
is equal to L"-m" (python-mmodule), prepend the current working directory.
If running a script (pythonscript.py), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.
Otherwise (python-ccode and python), prepend an empty string, which means the current working directory.
Set to 1 by the
command line option and the
environment variable.
Default: 0 in Python config, 1 in isolated config.
Added in version 3.11.
wchar_t*base_exec_prefix
.
Default: NULL.
Part of the
output.
See also
.
wchar_t*base_executable
Python base executable: sys._base_executable.
Set by the __PYVENV_LAUNCHER__ environment variable.
Set from
if NULL.
Default: NULL.
Part of the
output.
See also
.
wchar_t*base_prefix
.
Default: NULL.
Part of the
output.
See also
.
intbuffered_stdio
If equals to 0 and
is non-zero, disable buffering on the C streams stdout and stderr.
Set to 0 by the
command line option and the
environment variable.
stdin is always opened in buffered mode.
Default: 1.
intbytes_warning
If equals to 1, issue a warning when comparing
or
with
, or comparing bytes with
.
If equal or greater to 2, raise a
exception in these cases.
Incremented by the
command line option.
Default: 0.
intwarn_default_encoding
If non-zero, emit a
warning when
uses its default encoding. See
for details.
Default: 0.
Added in version 3.10.
intcode_debug_ranges
If equals to 0, disables the inclusion of the end line and column mappings in code objects. Also disables traceback printing carets to specific error locations.
Set to 0 by the
environment variable and by the
command line option.
Default: 1.
Added in version 3.11.
wchar_t*check_hash_pycs_mode
Control the validation behavior of hash-based .pyc files: value of the
command line option.
Valid values:
L"always": Hash the source file for invalidation regardless of value of the ‘check_source’ flag.
L"never": Assume that hash-based pycs always are valid.
L"default": The ‘check_source’ flag in hash-based pycs determines invalidation.
Default: L"default".
See also
“Deterministic pycs”.
intconfigure_c_stdio
If non-zero, configure C standard streams:
On Windows, set the binary mode (O_BINARY) on stdin, stdout and stderr.
If
equals zero, disable buffering of stdin, stdout and stderr streams.
If
is non-zero, enable stream buffering on stdin and stdout (only stdout on Windows).
Default: 1 in Python config, 0 in isolated config.
intdev_mode
If non-zero, enable the
.
Set to 1 by the
option and the
environment variable.
Default: -1 in Python mode, 0 in isolated mode.
intdump_refs
Dump Python references?
If non-zero, dump all objects which are still alive at exit.
Set to 1 by the
environment variable.
Needs a special build of Python with the Py_TRACE_REFS macro defined: see the
configure --with-trace-refs option
.
Default: 0.
wchar_t*dump_refs_file
Filename where to dump Python references.
Set by the
environment variable.
Default: NULL.
Added in version 3.11.
wchar_t*exec_prefix
The site-specific directory prefix where the platform-dependent Python files are installed:
.
Default: NULL.
Part of the
output.
See also
.
wchar_t*executable
The absolute path of the executable binary for the Python interpreter:
.
Default: NULL.
Part of the
output.
See also
.
intfaulthandler
Enable faulthandler?
If non-zero, call
at startup.
Set to 1 by
and the
environment variable.
Default: -1 in Python mode, 0 in isolated mode.
wchar_t*filesystem_encoding
:
.
On macOS, Android and VxWorks: use "utf-8" by default.
On Windows: use "utf-8" by default, or "mbcs" if
of
is non-zero.
Default encoding on other platforms:
"utf-8" if
is non-zero.
"ascii" if Python detects that nl_langinfo(CODESET) announces the ASCII encoding, whereas the mbstowcs() function decodes from a different encoding (usually Latin1).
"utf-8" if nl_langinfo(CODESET) returns an empty string.
Otherwise, use the
: nl_langinfo(CODESET) result.
At Python startup, the encoding name is normalized to the Python codec name. For example, "ANSI_X3.4-1968" is replaced with "ascii".
See also the
member.
wchar_t*filesystem_errors
:
sys.getfilesystemencodeerrors()
.
On Windows: use "surrogatepass" by default, or "replace" if
of
is non-zero.
On other platforms: use "surrogateescape" by default.
Supported error handlers:
"strict"
"surrogateescape"
"surrogatepass" (only supported with the UTF-8 encoding)
See also the
member.
intuse_frozen_modules
If non-zero, use frozen modules.
Set by the
environment variable.
Default: 1 in a release build, or 0 in a
.
unsignedlonghash_seed
intuse_hash_seed
Randomized hash function seed.
If
is zero, a seed is chosen randomly at Python startup, and
is ignored.
Set by the
environment variable.
Default use_hash_seed value: -1 in Python mode, 0 in isolated mode.
wchar_t*home
Set the default Python “home” directory, that is, the location of the standard Python libraries (see
).
Set by the
environment variable.
Default: NULL.
Part of the
input.
intimport_time
If 1, profile import time. If 2, include additional output that indicates when an imported module has already been loaded.
Set by the
option and the
environment variable.
Default: 0.
Changed in version 3.14: Added support for import_time=2
intinspect
Enter interactive mode after executing a script or a command.
If greater than 0, enable inspect: when a script is passed as first argument or the -c option is used, enter interactive mode after executing the script or the command, even when
does not appear to be a terminal.
Incremented by the
command line option. Set to 1 if the
environment variable is non-empty.
Default: 0.
intinstall_signal_handlers
Install Python signal handlers?
Default: 1 in Python mode, 0 in isolated mode.
intinteractive
If greater than 0, enable the interactive mode (REPL).
Incremented by the
command line option.
Default: 0.
intint_max_str_digits
Configures the
integer string conversion length limitation
. An initial value of -1 means the value will be taken from the command line or environment or otherwise default to 4300 (
sys.int_info.default_max_str_digits
). A value of 0 disables the limitation. Values greater than zero but less than 640 (
sys.int_info.str_digits_check_threshold
) are unsupported and will produce an error.
Configured by the
command line flag or the
environment variable.
Default: -1 in Python mode. 4300 (
sys.int_info.default_max_str_digits
) in isolated mode.
Added in version 3.12.
intcpu_count
If the value of
is not -1 then it will override the return values of
,
, and
.
Configured by the -Xcpu_count=n|default command line flag or the
environment variable.
Default: -1.
Added in version 3.13.
intisolated
If greater than 0, enable isolated mode:
Set
to 1: don’t prepend a potentially unsafe path to
at Python startup, such as the current directory, the script’s directory or an empty string.
Set
to 0: ignore PYTHON environment variables.
Set
to 0: don’t add the user site directory to
.
Python REPL doesn’t import
nor enable default readline configuration on interactive prompts.
Set to 1 by the
command line option.
Default: 0 in Python mode, 1 in isolated mode.
See also the
and
.
intlegacy_windows_stdio
If non-zero, use
instead of io._WindowsConsoleIO for
,
and
.
Set to 1 if the
environment variable is set to a non-empty string.
Only available on Windows. #ifdefMS_WINDOWS macro can be used for Windows specific code.
Default: 0.
See also the
(Change Windows console encoding to UTF-8).
intmalloc_stats
If non-zero, dump statistics on
Python pymalloc memory allocator
at exit.
Set to 1 by the
environment variable.
The option is ignored if Python is
configured using the --without-pymalloc option
.
Default: 0.
wchar_t*platlibdir
Platform library directory name:
.
Set by the
environment variable.
Default: value of the PLATLIBDIR macro which is set by the
configure --with-platlibdir option
(default: "lib", or "DLLs" on Windows).
Part of the
input.
Added in version 3.9.
Changed in version 3.11: This macro is now used on Windows to locate the standard library extension modules, typically under DLLs. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.
wchar_t*pythonpath_env
Module search paths (
) as a string separated by DELIM (
).
Set by the
environment variable.
Default: NULL.
Part of the
input.
module_search_paths
intmodule_search_paths_set
Module search paths:
.
If
is equal to 0,
will replace
and sets module_search_paths_set to 1.
Default: empty list (module_search_paths) and 0 (module_search_paths_set).
Part of the
output.
intoptimization_level
Compilation optimization level:
0: Peephole optimizer, set __debug__ to True.
1: Level 0, remove assertions, set __debug__ to False.
2: Level 1, strip docstrings.
Incremented by the
command line option. Set to the
environment variable value.
Default: 0.
orig_argv
The list of the original command line arguments passed to the Python executable:
.
If
list is empty and
is not a list only containing an empty string,
copies argv into orig_argv before modifying argv (if
is non-zero).
See also the
member and the
function.
Default: empty list.
Added in version 3.10.
intparse_argv
Parse command line arguments?
If equals to 1, parse
the same way the regular Python parses
, and strip Python arguments from argv.
The
function only parses
arguments once:
is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.
Default: 1 in Python mode, 0 in isolated mode.
Changed in version 3.10: The
arguments are now only parsed if
equals to 1.
intparser_debug
Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending on compilation options).
Incremented by the
command line option. Set to the
environment variable value.
Needs a
(the Py_DEBUG macro must be defined).
Default: 0.
intpathconfig_warnings
If non-zero, calculation of path configuration is allowed to log warnings into stderr. If equals to 0, suppress these warnings.
Default: 1 in Python mode, 0 in isolated mode.
Part of the
input.
Changed in version 3.11: Now also applies on Windows.
wchar_t*prefix
The site-specific directory prefix where the platform independent Python files are installed:
.
Default: NULL.
Part of the
output.
See also
.
wchar_t*program_name
Program name used to initialize
and in early error messages during Python initialization.
On macOS, use
environment variable if set.
If the WITH_NEXT_FRAMEWORK macro is defined, use __PYVENV_LAUNCHER__ environment variable if set.
Use argv[0] of
if available and non-empty.
Otherwise, use L"python" on Windows, or L"python3" on other platforms.
Default: NULL.
Part of the
input.
wchar_t*pycache_prefix
Directory where cached .pyc files are written:
.
Set by the
command line option and the
environment variable. The command-line option takes precedence.
If NULL,
is set to None.
Default: NULL.
intquiet
Quiet mode. If greater than 0, don’t display the copyright and version at Python startup in interactive mode.
Incremented by the
command line option.
Default: 0.
wchar_t*run_command
Value of the
command line option.
Used by
.
Default: NULL.
wchar_t*run_filename
Filename passed on the command line: trailing command line argument without
or
. It is used by the
function.
For example, it is set to script.py by the python3script.pyarg command line.
See also the
PyConfig.skip_source_first_line
option.
Default: NULL.
wchar_t*run_module
Value of the
command line option.
Used by
.
Default: NULL.
wchar_t*run_presite
package.module path to module that should be imported before site.py is run.
Set by the
command-line option and the
environment variable. The command-line option takes precedence.
Needs a
(the Py_DEBUG macro must be defined).
Default: NULL.
intshow_ref_count
Show total reference count at exit (excluding
objects)?
Set to 1 by
command line option.
Needs a
(the Py_REF_DEBUG macro must be defined).
Default: 0.
intsite_import
Import the
module at startup?
If equal to zero, disable the import of the module site and the site-dependent manipulations of
that it entails.
Also disable these manipulations if the
module is explicitly imported later (call
if you want them to be triggered).
Set to 0 by the
command line option.
is set to the inverted value of
.
Default: 1.
intskip_source_first_line
If non-zero, skip the first line of the
source.
It allows the usage of non-Unix forms of #!cmd. This is intended for a DOS specific hack only.
Set to 1 by the
command line option.
Default: 0.
wchar_t*stdio_encoding
wchar_t*stdio_errors
Encoding and encoding errors of
,
and
(but sys.stderr always uses "backslashreplace" error handler).
Use the
environment variable if it is non-empty.
Default encoding:
"UTF-8" if
is non-zero.
Otherwise, use the
.
Default error handler:
On Windows: use "surrogateescape".
"surrogateescape" if
is non-zero, or if the LC_CTYPE locale is “C” or “POSIX”.
"strict" otherwise.
See also
.
inttracemalloc
Enable tracemalloc?
If non-zero, call
at startup.
Set by
command line option and by the
environment variable.
Default: -1 in Python mode, 0 in isolated mode.
intperf_profiling
Enable the Linux perf profiler support?
If equals to 1, enable support for the Linux perf profiler.
If equals to 2, enable support for the Linux perf profiler with DWARF JIT support.
Set to 1 by
command-line option and the
environment variable.
Set to 2 by the
command-line option and the
environment variable.
Default: -1.
Added in version 3.12.
wchar_t*stdlib_dir
Directory of the Python standard library.
Default: NULL.
Added in version 3.11.
intuse_environment
Use
?
If equals to zero, ignore the
.
Set to 0 by the
environment variable.
Default: 1 in Python config and 0 in isolated config.
intuse_system_logger
If non-zero, stdout and stderr will be redirected to the system log.
Only available on macOS 10.12 and later, and on iOS.
Default: 0 (don’t use the system log) on macOS; 1 on iOS (use the system log).
Added in version 3.14.
intuser_site_directory
If non-zero, add the user site directory to
.
Set to 0 by the
and
command line options.
Set to 0 by the
environment variable.
Default: 1 in Python mode, 0 in isolated mode.
intverbose
Verbose mode. If greater than 0, print a message each time a module is imported, showing the place (filename or built-in module) from which it is loaded.
If greater than or equal to 2, print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.
Incremented by the
command line option.
Set by the
environment variable value.
Default: 0.
warnoptions
Options of the
module to build warnings filters, lowest to highest priority:
.
The
module adds
in the reverse order: the last
item becomes the first item of warnings.filters which is checked first (highest priority).
The
command line options adds its value to
, it can be used multiple times.
The
environment variable can also be used to add warning options. Multiple options can be specified, separated by commas (,).
Default: empty list.
intwrite_bytecode
If equal to 0, Python won’t try to write .pyc files on the import of source modules.
Set to 0 by the
command line option and the
environment variable.
is initialized to the inverted value of
.
Default: 1.
xoptions
Values of the
command line options:
.
Default: empty list.
int_pystats
If non-zero, write performance statistics at Python exit.
Need a special build with the Py_STATS macro: see
.
Default: 0.
If
is non-zero,
arguments are parsed the same way the regular Python parses
, and Python arguments are stripped from argv.
The
options are parsed to set other options: see the
command line option.
Changed in version 3.9: The show_alloc_count field has been removed.
Initialization with PyConfig
Initializing the interpreter from a populated configuration struct is handled by calling
.
The caller is responsible to handle exceptions (error or exit) using
and
.
If
,
or
are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times, PyImport_AppendInittab() or PyImport_ExtendInittab() must be called before each Python initialization.
The current configuration (PyConfig type) is stored in PyInterpreterState.config.
Example setting the program name:
voidinit_python(void){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);/* Set the program name. Implicitly preinitialize Python. */status=PyConfig_SetString(&config,&config.program_name,L"/path/to/my_program");if(PyStatus_Exception(status)){gotoexception;}status=Py_InitializeFromConfig(&config);if(PyStatus_Exception(status)){gotoexception;}PyConfig_Clear(&config);return;exception:PyConfig_Clear(&config);Py_ExitStatusException(status);}More complete example modifying the default configuration, read the configuration, and then override some parameters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:
PyStatusinit_python(constchar*program_name){PyStatusstatus;PyConfigconfig;PyConfig_InitPythonConfig(&config);/* Set the program name before reading the configuration (decode byte string from the locale encoding). Implicitly preinitialize Python. */status=PyConfig_SetBytesString(&config,&config.program_name,program_name);if(PyStatus_Exception(status)){gotodone;}/* Read all configuration at once */status=PyConfig_Read(&config);if(PyStatus_Exception(status)){gotodone;}/* Specify sys.path explicitly *//* If you want to modify the default set of paths, finish initialization first and then use PySys_GetObject("path") */config.module_search_paths_set=1;status=PyWideStringList_Append(&config.module_search_paths,L"/path/to/stdlib");if(PyStatus_Exception(status)){gotodone;}status=PyWideStringList_Append(&config.module_search_paths,L"/path/to/more/modules");if(PyStatus_Exception(status)){gotodone;}/* Override executable computed by PyConfig_Read() */status=PyConfig_SetString(&config,&config.executable,L"/path/to/my_executable");if(PyStatus_Exception(status)){gotodone;}status=Py_InitializeFromConfig(&config);done:PyConfig_Clear(&config);returnstatus;}Isolated Configuration
PyPreConfig_InitIsolatedConfig()
and
functions create a configuration to isolate Python from the system. For example, to embed Python into an application.
This configuration ignores global configuration variables, environment variables, command line arguments (
is not parsed) and user site directory. The C standard streams (ex: stdout) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Configuration files are still used with this configuration to determine paths that are unspecified. Ensure
is specified to avoid computing the default path configuration.
Python Configuration
PyPreConfig_InitPythonConfig()
and
functions create a configuration to build a customized Python which behaves as the regular Python.
Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored.
This function enables C locale coercion (
) and
(
) depending on the LC_CTYPE locale,
and
environment variables.
Python Path Configuration
contains multiple fields for the path configuration:
Path configuration inputs:
current working directory: to get absolute paths
PATH environment variable to get the program full path (from
)
__PYVENV_LAUNCHER__ environment variable
(Windows only) Application paths in the registry under “SoftwarePythonPythonCoreX.YPythonPath” of HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE (where X.Y is the Python version).
Path configuration output fields:
PyConfig.module_search_paths_set
,
If at least one “output field” is not set, Python calculates the path configuration to fill unset fields. If
is equal to 0,
is overridden and module_search_paths_set is set to 1.
It is possible to completely ignore the function calculating the default path configuration by setting explicitly all path configuration output fields listed above. A string is considered as set even if it is non-empty. module_search_paths is considered as set if module_search_paths_set is set to 1. In this case, module_search_paths will be used without modification.
Set
to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).
If
or
fields are not set, they inherit their value from
and
respectively.
and
modify
:
If
is set and is a directory which contains a __main__.py script, prepend run_filename to
.
If
is zero:
If
is set, prepend the current directory to
. Do nothing if the current directory cannot be read.
If
is set, prepend the directory of the filename to
.
Otherwise, prepend an empty string to
.
If
is non-zero,
can be modified by the
module. If
is non-zero and the user’s site-package directory exists, the site module appends the user’s site-package directory to sys.path.
The following configuration files are used by the path configuration:
pyvenv.cfg
._pth file (ex: python._pth)
pybuilddir.txt (Unix only)
If a ._pth file is present:
Set
to 1.
Set
to 0.
Set
to 0.
Set
to 1.
If
is not set and a pyvenv.cfg file is present in the same directory as
, or its parent,
and
are set that location. When this happens,
and
still keep their value, pointing to the base installation. See
for more information.
The __PYVENV_LAUNCHER__ environment variable is used to set
.
Changed in version 3.14:
, and
, are now set to the pyvenv.cfg directory. This was previously done by
, therefore affected by
.
Py_GetArgcArgv()
voidPy_GetArgcArgv(int*argc, wchar_t***argv)
Get the original command line arguments, before Python modified them.
See also
member.
Delaying main module execution
In some embedding use cases, it may be desirable to separate interpreter initialization from the execution of the main module.
This separation can be achieved by setting PyConfig.run_command to the empty string during initialization (to prevent the interpreter from dropping into the interactive prompt), and then subsequently executing the desired main module code using __main__.__dict__ as the global namespace.