Interpreter initialization and finalization

See Python Initialization Configuration for details on how to configure the interpreter prior to initialization.

Before Python initialization

In an application embedding Python, the Py_Initialize() function must be called before using any other Python/C API functions; with the exception of a few functions and the global configuration variables.

The following functions can be safely called before Python is initialized:

• Functions that initialize the interpreter:

  • Py_Initialize()

  • Py_InitializeEx()

  • Py_InitializeFromConfig()

  • Py_BytesMain()

  • Py_Main()

  • the runtime pre-initialization functions covered in Python Initialization Configuration

• Configuration functions:

  • PyImport_AppendInittab()

  • PyImport_ExtendInittab()

  • PyInitFrozenExtensions()

  • PyMem_SetAllocator()

  • PyMem_SetupDebugHooks()

  • PyObject_SetArenaAllocator()

  • Py_SetProgramName()

  • Py_SetPythonHome()

  • the configuration functions covered in Python Initialization Configuration

• Informative functions:

  • Py_IsInitialized()

  • PyMem_GetAllocator()

  • PyObject_GetArenaAllocator()

  • Py_GetBuildInfo()

  • Py_GetCompiler()

  • Py_GetCopyright()

  • Py_GetPlatform()

  • Py_GetVersion()

  • Py_IsInitialized()

• Utilities:

  • Py_DecodeLocale()

  • the status reporting and utility functions covered in Python Initialization Configuration

• Memory allocators:

  • PyMem_RawMalloc()

  • PyMem_RawRealloc()

  • PyMem_RawCalloc()

  • PyMem_RawFree()

• Synchronization:

  • PyMutex_Lock()

  • PyMutex_Unlock()

Note

Despite their apparent similarity to some of the functions listed above, the following functions should not be called before the interpreter has been initialized: Py_EncodeLocale(), PyEval_InitThreads(), and Py_RunMain().

Global configuration variables

Python has variables for the global configuration to control different features and options. By default, these flags are controlled by command line options.

When a flag is set by an option, the value of the flag is the number of times that the option was set. For example, -b sets Py_BytesWarningFlag to 1 and -bb sets Py_BytesWarningFlag to 2.

int Py_BytesWarningFlag

This API is kept for backward compatibility: setting PyConfig.bytes_warning should be used instead, see Python Initialization Configuration.

Issue a warning when comparing bytes or bytearray with str or bytes with int. Issue an error if greater or equal to 2.

Set by the -b option.

Deprecated since version 3.12, removed in version 3.15.

int Py_DebugFlag

This API is kept for backward compatibility: setting PyConfig.parser_debug should be used instead, see Python Initialization Configuration.

Turn on parser debugging output (for expert only, depending on compilation options).

Set by the -d option and the PYTHONDEBUG environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting PyConfig.write_bytecode should be used instead, see Python Initialization Configuration.

If set to non-zero, Python won’t try to write .pyc files on the import of source modules.

Set by the -B option and the PYTHONDONTWRITEBYTECODE environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_FrozenFlag

This API is kept for backward compatibility: setting PyConfig.pathconfig_warnings should be used instead, see Python Initialization Configuration.

Private flag used by _freeze_module and frozenmain programs.

Deprecated since version 3.12, removed in version 3.15.

int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting PyConfig.hash_seed and PyConfig.use_hash_seed should be used instead, see Python Initialization Configuration.

Set to 1 if the PYTHONHASHSEED environment variable is set to a non-empty string.

If the flag is non-zero, read the PYTHONHASHSEED environment variable to initialize the secret hash seed.

Deprecated since version 3.12, removed in version 3.15.

int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting PyConfig.use_environment should be used instead, see Python Initialization Configuration.

Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.

Set by the -E and -I options.

Deprecated since version 3.12, removed in version 3.15.

int Py_InspectFlag

This API is kept for backward compatibility: setting PyConfig.inspect should be used instead, see Python Initialization Configuration.

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 sys.stdin does not appear to be a terminal.

Set by the -i option and the PYTHONINSPECT environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_InteractiveFlag

This API is kept for backward compatibility: setting PyConfig.interactive should be used instead, see Python Initialization Configuration.

Set by the -i option.

Deprecated since version 3.12, removed in version 3.15.

int Py_IsolatedFlag

This API is kept for backward compatibility: setting PyConfig.isolated should be used instead, see Python Initialization Configuration.

Run Python in isolated mode. In isolated mode sys.path contains neither the script’s directory nor the user’s site-packages directory.

Set by the -I option.

Added in version 3.4.

Deprecated since version 3.12, removed in version 3.15.

int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting PyPreConfig.legacy_windows_fs_encoding should be used instead, see Python Initialization Configuration.

If the flag is non-zero, use the mbcs encoding with replace error handler, instead of the UTF-8 encoding with surrogatepass error handler, for the filesystem encoding and error handler.

Set to 1 if the PYTHONLEGACYWINDOWSFSENCODING environment variable is set to a non-empty string.

See PEP 529 for more details.

Availability: Windows.

Deprecated since version 3.12, removed in version 3.15.

int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting PyConfig.legacy_windows_stdio should be used instead, see Python Initialization Configuration.

If the flag is non-zero, use io.FileIO instead of io._WindowsConsoleIO for sys standard streams.

Set to 1 if the PYTHONLEGACYWINDOWSSTDIO environment variable is set to a non-empty string.

See PEP 528 for more details.

Availability: Windows.

Deprecated since version 3.12, removed in version 3.15.

int Py_NoSiteFlag

This API is kept for backward compatibility: setting PyConfig.site_import should be used instead, see Python Initialization Configuration.

Disable the import of the module site and the site-dependent manipulations of sys.path that it entails. Also disable these manipulations if site is explicitly imported later (call site.main() if you want them to be triggered).

Set by the -S option.

Deprecated since version 3.12, removed in version 3.15.

int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting PyConfig.user_site_directory should be used instead, see Python Initialization Configuration.

Don’t add the user site-packages directory to sys.path.

Set by the -s and -I options, and the PYTHONNOUSERSITE environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_OptimizeFlag

This API is kept for backward compatibility: setting PyConfig.optimization_level should be used instead, see Python Initialization Configuration.

Set by the -O option and the PYTHONOPTIMIZE environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_QuietFlag

This API is kept for backward compatibility: setting PyConfig.quiet should be used instead, see Python Initialization Configuration.

Don’t display the copyright and version messages even in interactive mode.

Set by the -q option.

Added in version 3.2.

Deprecated since version 3.12, removed in version 3.15.

int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting PyConfig.buffered_stdio should be used instead, see Python Initialization Configuration.

Force the stdout and stderr streams to be unbuffered.

Set by the -u option and the PYTHONUNBUFFERED environment variable.

Deprecated since version 3.12, removed in version 3.15.

int Py_VerboseFlag

This API is kept for backward compatibility: setting PyConfig.verbose should be used instead, see Python Initialization Configuration.

Print a message each time a module is initialized, showing the place (filename or built-in module) from which it is loaded. If greater 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.

Set by the -v option and the PYTHONVERBOSE environment variable.

Deprecated since version 3.12, removed in version 3.15.

Initializing and finalizing the interpreter

void Py_Initialize()

Part of the Stable ABI.

Initialize the Python interpreter. In an application embedding Python, this should be called before using any other Python/C API functions; see Before Python Initialization for the few exceptions.

This initializes the table of loaded modules (sys.modules), and creates the fundamental modules builtins, __main__ and sys. It also initializes the module search path (sys.path). It does not set sys.argv; use the Python Initialization Configuration API for that. This is a no-op when called for a second time (without calling