path: root/devdocs/python~3.12/c-api%2Finit_config.html

 <span id="init-config"></span><h1>Python Initialization Configuration</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> <p>Python can be initialized with <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code>Py_InitializeFromConfig()</code></a> and the <a class="reference internal" href="#c.PyConfig" title="PyConfig"><code>PyConfig</code></a> structure. It can be preinitialized with <a class="reference internal" href="#c.Py_PreInitialize" title="Py_PreInitialize"><code>Py_PreInitialize()</code></a> and the <a class="reference internal" href="#c.PyPreConfig" title="PyPreConfig"><code>PyPreConfig</code></a> structure.</p> <p>There are two kinds of configuration:</p> <ul class="simple"> <li>The <a class="reference internal" href="#init-python-config"><span class="std std-ref">Python Configuration</span></a> 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.</li> <li>The <a class="reference internal" href="#init-isolated-conf"><span class="std std-ref">Isolated Configuration</span></a> 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.</li> </ul> <p>The <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a> function can be used to write a customized Python program.</p> <p>See also <a class="reference internal" href="init#initialization"><span class="std std-ref">Initialization, Finalization, and Threads</span></a>.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0587/"><strong>PEP 587</strong></a> “Python Initialization Configuration”.</p> </div> <section id="example"> <h2>Example</h2> <p>Example of customized Python always running in isolated mode:</p> <pre data-language="c">int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&amp;config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&amp;config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&amp;config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&amp;config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&amp;config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}
</pre> </section> <section id="pywidestringlist"> <h2>PyWideStringList</h2> <dl class="c type"> <dt class="sig sig-object c" id="c.PyWideStringList">
<code>type PyWideStringList</code> </dt> <dd>
<p>List of <code>wchar_t*</code> strings.</p> <p>If <em>length</em> is non-zero, <em>items</em> must be non-<code>NULL</code> and all strings must be non-<code>NULL</code>.</p> <p>Methods:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWideStringList_Append">
<code>PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)</code> </dt> <dd>
<p>Append <em>item</em> to <em>list</em>.</p> <p>Python must be preinitialized to call this function.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWideStringList_Insert">
<code>PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)</code> </dt> <dd>
<p>Insert <em>item</em> into <em>list</em> at <em>index</em>.</p> <p>If <em>index</em> is greater than or equal to <em>list</em> length, append <em>item</em> to <em>list</em>.</p> <p><em>index</em> must be greater than or equal to <code>0</code>.</p> <p>Python must be preinitialized to call this function.</p> </dd>
</dl> <p>Structure fields:</p> <dl class="c member"> <dt class="sig sig-object c" id="c.PyWideStringList.length">
<code>Py_ssize_t length</code> </dt> <dd>
<p>List length.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyWideStringList.items">
<code>wchar_t **items</code> </dt> <dd>
<p>List items.</p> </dd>
</dl> </dd>
</dl> </section> <section id="pystatus"> <h2>PyStatus</h2> <dl class="c type"> <dt class="sig sig-object c" id="c.PyStatus">
<code>type PyStatus</code> </dt> <dd>
<p>Structure to store an initialization function status: success, error or exit.</p> <p>For an error, it can store the C function name which created the error.</p> <p>Structure fields:</p> <dl class="c member"> <dt class="sig sig-object c" id="c.PyStatus.exitcode">
<code>int exitcode</code> </dt> <dd>
<p>Exit code. Argument passed to <code>exit()</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyStatus.err_msg">
<code>const char *err_msg</code> </dt> <dd>
<p>Error message.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyStatus.func">
<code>const char *func</code> </dt> <dd>
<p>Name of the function which created an error, can be <code>NULL</code>.</p> </dd>
</dl> <p>Functions to create a status:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_Ok">
<code>PyStatus PyStatus_Ok(void)</code> </dt> <dd>
<p>Success.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_Error">
<code>PyStatus PyStatus_Error(const char *err_msg)</code> </dt> <dd>
<p>Initialization error with a message.</p> <p><em>err_msg</em> must not be <code>NULL</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_NoMemory">
<code>PyStatus PyStatus_NoMemory(void)</code> </dt> <dd>
<p>Memory allocation failure (out of memory).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_Exit">
<code>PyStatus PyStatus_Exit(int exitcode)</code> </dt> <dd>
<p>Exit Python with the specified exit code.</p> </dd>
</dl> <p>Functions to handle a status:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_Exception">
<code>int PyStatus_Exception(PyStatus status)</code> </dt> <dd>
<p>Is the status an error or an exit? If true, the exception must be handled; by calling <a class="reference internal" href="#c.Py_ExitStatusException" title="Py_ExitStatusException"><code>Py_ExitStatusException()</code></a> for example.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_IsError">
<code>int PyStatus_IsError(PyStatus status)</code> </dt> <dd>
<p>Is the result an error?</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyStatus_IsExit">
<code>int PyStatus_IsExit(PyStatus status)</code> </dt> <dd>
<p>Is the result an exit?</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_ExitStatusException">
<code>void Py_ExitStatusException(PyStatus status)</code> </dt> <dd>
<p>Call <code>exit(exitcode)</code> if <em>status</em> is an exit. Print the error message and exit with a non-zero exit code if <em>status</em> is an error. Must only be called if <code>PyStatus_Exception(status)</code> is non-zero.</p> </dd>
</dl> </dd>
</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Internally, Python uses macros which set <code>PyStatus.func</code>, whereas functions to create a status set <code>func</code> to <code>NULL</code>.</p> </div> <p>Example:</p> <pre data-language="c">PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&amp;ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}
</pre> </section> <section id="pypreconfig"> <h2>PyPreConfig</h2> <dl class="c type"> <dt class="sig sig-object c" id="c.PyPreConfig">
<code>type PyPreConfig</code> </dt> <dd>
<p>Structure used to preinitialize Python.</p> <p>Function to initialize a preconfiguration:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyPreConfig_InitPythonConfig">
<code>void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)</code> </dt> <dd>
<p>Initialize the preconfiguration with <a class="reference internal" href="#init-python-config"><span class="std std-ref">Python Configuration</span></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyPreConfig_InitIsolatedConfig">
<code>void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)</code> </dt> <dd>
<p>Initialize the preconfiguration with <a class="reference internal" href="#init-isolated-conf"><span class="std std-ref">Isolated Configuration</span></a>.</p> </dd>
</dl> <p>Structure fields:</p> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.allocator">
<code>int allocator</code> </dt> <dd>
<p>Name of the Python memory allocators:</p> <ul class="simple"> <li>
<code>PYMEM_ALLOCATOR_NOT_SET</code> (<code>0</code>): don’t change memory allocators (use defaults).</li> <li>
<code>PYMEM_ALLOCATOR_DEFAULT</code> (<code>1</code>): <a class="reference internal" href="memory#default-memory-allocators"><span class="std std-ref">default memory allocators</span></a>.</li> <li>
<code>PYMEM_ALLOCATOR_DEBUG</code> (<code>2</code>): <a class="reference internal" href="memory#default-memory-allocators"><span class="std std-ref">default memory allocators</span></a> with <a class="reference internal" href="memory#pymem-debug-hooks"><span class="std std-ref">debug hooks</span></a>.</li> <li>
<code>PYMEM_ALLOCATOR_MALLOC</code> (<code>3</code>): use <code>malloc()</code> of the C library.</li> <li>
<code>PYMEM_ALLOCATOR_MALLOC_DEBUG</code> (<code>4</code>): force usage of <code>malloc()</code> with <a class="reference internal" href="memory#pymem-debug-hooks"><span class="std std-ref">debug hooks</span></a>.</li> <li>
<code>PYMEM_ALLOCATOR_PYMALLOC</code> (<code>5</code>): <a class="reference internal" href="memory#pymalloc"><span class="std std-ref">Python pymalloc memory allocator</span></a>.</li> <li>
<code>PYMEM_ALLOCATOR_PYMALLOC_DEBUG</code> (<code>6</code>): <a class="reference internal" href="memory#pymalloc"><span class="std std-ref">Python pymalloc memory allocator</span></a> with <a class="reference internal" href="memory#pymem-debug-hooks"><span class="std std-ref">debug hooks</span></a>.</li> </ul> <p><code>PYMEM_ALLOCATOR_PYMALLOC</code> and <code>PYMEM_ALLOCATOR_PYMALLOC_DEBUG</code> are not supported if Python is <a class="reference internal" href="../using/configure#cmdoption-without-pymalloc"><code>configured using --without-pymalloc</code></a>.</p> <p>See <a class="reference internal" href="memory#memory"><span class="std std-ref">Memory Management</span></a>.</p> <p>Default: <code>PYMEM_ALLOCATOR_NOT_SET</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.configure_locale">
<code>int configure_locale</code> </dt> <dd>
<p>Set the LC_CTYPE locale to the user preferred locale.</p> <p>If equals to <code>0</code>, set <a class="reference internal" href="#c.PyPreConfig.coerce_c_locale" title="PyPreConfig.coerce_c_locale"><code>coerce_c_locale</code></a> and <a class="reference internal" href="#c.PyPreConfig.coerce_c_locale_warn" title="PyPreConfig.coerce_c_locale_warn"><code>coerce_c_locale_warn</code></a> members to <code>0</code>.</p> <p>See the <a class="reference internal" href="../glossary#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>.</p> <p>Default: <code>1</code> in Python config, <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.coerce_c_locale">
<code>int coerce_c_locale</code> </dt> <dd>
<p>If equals to <code>2</code>, coerce the C locale.</p> <p>If equals to <code>1</code>, read the LC_CTYPE locale to decide if it should be coerced.</p> <p>See the <a class="reference internal" href="../glossary#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>.</p> <p>Default: <code>-1</code> in Python config, <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.coerce_c_locale_warn">
<code>int coerce_c_locale_warn</code> </dt> <dd>
<p>If non-zero, emit a warning if the C locale is coerced.</p> <p>Default: <code>-1</code> in Python config, <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.dev_mode">
<code>int dev_mode</code> </dt> <dd>
<p><a class="reference internal" href="../library/devmode#devmode"><span class="std std-ref">Python Development Mode</span></a>: see <a class="reference internal" href="#c.PyConfig.dev_mode" title="PyConfig.dev_mode"><code>PyConfig.dev_mode</code></a>.</p> <p>Default: <code>-1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.isolated">
<code>int isolated</code> </dt> <dd>
<p>Isolated mode: see <a class="reference internal" href="#c.PyConfig.isolated" title="PyConfig.isolated"><code>PyConfig.isolated</code></a>.</p> <p>Default: <code>0</code> in Python mode, <code>1</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.legacy_windows_fs_encoding">
<code>int legacy_windows_fs_encoding</code> </dt> <dd>
<p>If non-zero:</p> <ul class="simple"> <li>Set <a class="reference internal" href="#c.PyPreConfig.utf8_mode" title="PyPreConfig.utf8_mode"><code>PyPreConfig.utf8_mode</code></a> to <code>0</code>,</li> <li>Set <a class="reference internal" href="#c.PyConfig.filesystem_encoding" title="PyConfig.filesystem_encoding"><code>PyConfig.filesystem_encoding</code></a> to <code>"mbcs"</code>,</li> <li>Set <a class="reference internal" href="#c.PyConfig.filesystem_errors" title="PyConfig.filesystem_errors"><code>PyConfig.filesystem_errors</code></a> to <code>"replace"</code>.</li> </ul> <p>Initialized the from <span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONLEGACYWINDOWSFSENCODING"><code>PYTHONLEGACYWINDOWSFSENCODING</code></a> environment variable value.</p> <p>Only available on Windows. <code>#ifdef MS_WINDOWS</code> macro can be used for Windows specific code.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.parse_argv">
<code>int parse_argv</code> </dt> <dd>
<p>If non-zero, <a class="reference internal" href="#c.Py_PreInitializeFromArgs" title="Py_PreInitializeFromArgs"><code>Py_PreInitializeFromArgs()</code></a> and <a class="reference internal" href="#c.Py_PreInitializeFromBytesArgs" title="Py_PreInitializeFromBytesArgs"><code>Py_PreInitializeFromBytesArgs()</code></a> parse their <code>argv</code> argument the same way the regular Python parses command line arguments: see <a class="reference internal" href="../using/cmdline#using-on-cmdline"><span class="std std-ref">Command Line Arguments</span></a>.</p> <p>Default: <code>1</code> in Python config, <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.use_environment">
<code>int use_environment</code> </dt> <dd>
<p>Use <a class="reference internal" href="../using/cmdline#using-on-envvars"><span class="std std-ref">environment variables</span></a>? See <a class="reference internal" href="#c.PyConfig.use_environment" title="PyConfig.use_environment"><code>PyConfig.use_environment</code></a>.</p> <p>Default: <code>1</code> in Python config and <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyPreConfig.utf8_mode">
<code>int utf8_mode</code> </dt> <dd>
<p>If non-zero, enable the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p> <p>Set to <code>0</code> or <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X utf8</code></a> command line option and the <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONUTF8"><code>PYTHONUTF8</code></a> environment variable.</p> <p>Also set to <code>1</code> if the <code>LC_CTYPE</code> locale is <code>C</code> or <code>POSIX</code>.</p> <p>Default: <code>-1</code> in Python config and <code>0</code> in isolated config.</p> </dd>
</dl> </dd>
</dl> </section> <section id="preinitialize-python-with-pypreconfig"> <span id="c-preinit"></span><h2>Preinitialize Python with PyPreConfig</h2> <p>The preinitialization of Python:</p> <ul class="simple"> <li>Set the Python memory allocators (<a class="reference internal" href="#c.PyPreConfig.allocator" title="PyPreConfig.allocator"><code>PyPreConfig.allocator</code></a>)</li> <li>Configure the LC_CTYPE locale (<a class="reference internal" href="../glossary#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>)</li> <li>Set the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a> (<a class="reference internal" href="#c.PyPreConfig.utf8_mode" title="PyPreConfig.utf8_mode"><code>PyPreConfig.utf8_mode</code></a>)</li> </ul> <p>The current preconfiguration (<code>PyPreConfig</code> type) is stored in <code>_PyRuntime.preconfig</code>.</p> <p>Functions to preinitialize Python:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_PreInitialize">
<code>PyStatus Py_PreInitialize(const PyPreConfig *preconfig)</code> </dt> <dd>
<p>Preinitialize Python from <em>preconfig</em> preconfiguration.</p> <p><em>preconfig</em> must not be <code>NULL</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_PreInitializeFromBytesArgs">
<code>PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)</code> </dt> <dd>
<p>Preinitialize Python from <em>preconfig</em> preconfiguration.</p> <p>Parse <em>argv</em> command line arguments (bytes strings) if <a class="reference internal" href="#c.PyPreConfig.parse_argv" title="PyPreConfig.parse_argv"><code>parse_argv</code></a> of <em>preconfig</em> is non-zero.</p> <p><em>preconfig</em> must not be <code>NULL</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_PreInitializeFromArgs">
<code>PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)</code> </dt> <dd>
<p>Preinitialize Python from <em>preconfig</em> preconfiguration.</p> <p>Parse <em>argv</em> command line arguments (wide strings) if <a class="reference internal" href="#c.PyPreConfig.parse_argv" title="PyPreConfig.parse_argv"><code>parse_argv</code></a> of <em>preconfig</em> is non-zero.</p> <p><em>preconfig</em> must not be <code>NULL</code>.</p> </dd>
</dl> <p>The caller is responsible to handle exceptions (error or exit) using <a class="reference internal" href="#c.PyStatus_Exception" title="PyStatus_Exception"><code>PyStatus_Exception()</code></a> and <a class="reference internal" href="#c.Py_ExitStatusException" title="Py_ExitStatusException"><code>Py_ExitStatusException()</code></a>.</p> <p>For <a class="reference internal" href="#init-python-config"><span class="std std-ref">Python Configuration</span></a> (<a class="reference internal" href="#c.PyPreConfig_InitPythonConfig" title="PyPreConfig_InitPythonConfig"><code>PyPreConfig_InitPythonConfig()</code></a>), 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 <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X utf8</code></a> command line option enables the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p> <p><code>PyMem_SetAllocator()</code> can be called after <a class="reference internal" href="#c.Py_PreInitialize" title="Py_PreInitialize"><code>Py_PreInitialize()</code></a> and before <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code>Py_InitializeFromConfig()</code></a> to install a custom memory allocator. It can be called before <a class="reference internal" href="#c.Py_PreInitialize" title="Py_PreInitialize"><code>Py_PreInitialize()</code></a> if <a class="reference internal" href="#c.PyPreConfig.allocator" title="PyPreConfig.allocator"><code>PyPreConfig.allocator</code></a> is set to <code>PYMEM_ALLOCATOR_NOT_SET</code>.</p> <p>Python memory allocation functions like <a class="reference internal" href="memory#c.PyMem_RawMalloc" title="PyMem_RawMalloc"><code>PyMem_RawMalloc()</code></a> must not be used before the Python preinitialization, whereas calling directly <code>malloc()</code> and <code>free()</code> is always safe. <a class="reference internal" href="sys#c.Py_DecodeLocale" title="Py_DecodeLocale"><code>Py_DecodeLocale()</code></a> must not be called before the Python preinitialization.</p> <p>Example using the preinitialization to enable the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>:</p> <pre data-language="c">PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&amp;preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&amp;preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();
</pre> </section> <section id="pyconfig"> <h2>PyConfig</h2> <dl class="c type"> <dt class="sig sig-object c" id="c.PyConfig">
<code>type PyConfig</code> </dt> <dd>
<p>Structure containing most parameters to configure Python.</p> <p>When done, the <a class="reference internal" href="#c.PyConfig_Clear" title="PyConfig_Clear"><code>PyConfig_Clear()</code></a> function must be used to release the configuration memory.</p> <p>Structure methods:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_InitPythonConfig">
<code>void PyConfig_InitPythonConfig(PyConfig *config)</code> </dt> <dd>
<p>Initialize configuration with the <a class="reference internal" href="#init-python-config"><span class="std std-ref">Python Configuration</span></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_InitIsolatedConfig">
<code>void PyConfig_InitIsolatedConfig(PyConfig *config)</code> </dt> <dd>
<p>Initialize configuration with the <a class="reference internal" href="#init-isolated-conf"><span class="std std-ref">Isolated Configuration</span></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_SetString">
<code>PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)</code> </dt> <dd>
<p>Copy the wide character string <em>str</em> into <code>*config_str</code>.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_SetBytesString">
<code>PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)</code> </dt> <dd>
<p>Decode <em>str</em> using <a class="reference internal" href="sys#c.Py_DecodeLocale" title="Py_DecodeLocale"><code>Py_DecodeLocale()</code></a> and set the result into <code>*config_str</code>.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_SetArgv">
<code>PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)</code> </dt> <dd>
<p>Set command line arguments (<a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> member of <em>config</em>) from the <em>argv</em> list of wide character strings.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_SetBytesArgv">
<code>PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)</code> </dt> <dd>
<p>Set command line arguments (<a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> member of <em>config</em>) from the <em>argv</em> list of bytes strings. Decode bytes using <a class="reference internal" href="sys#c.Py_DecodeLocale" title="Py_DecodeLocale"><code>Py_DecodeLocale()</code></a>.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_SetWideStringList">
<code>PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)</code> </dt> <dd>
<p>Set the list of wide strings <em>list</em> to <em>length</em> and <em>items</em>.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_Read">
<code>PyStatus PyConfig_Read(PyConfig *config)</code> </dt> <dd>
<p>Read all Python configuration.</p> <p>Fields which are already initialized are left unchanged.</p> <p>Fields for <a class="reference internal" href="#init-path-config"><span class="std std-ref">path configuration</span></a> are no longer calculated or modified when calling this function, as of Python 3.11.</p> <p>The <a class="reference internal" href="#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a> function only parses <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a> arguments once: <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a> is set to <code>2</code> after arguments are parsed. Since Python arguments are strippped from <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a>, parsing arguments twice would parse the application options as Python options.</p> <p><a class="reference internal" href="#c-preinit"><span class="std std-ref">Preinitialize Python</span></a> if needed.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a> arguments are now only parsed once, <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a> is set to <code>2</code> after arguments are parsed, and arguments are only parsed if <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a> equals <code>1</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span><a class="reference internal" href="#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a> no longer calculates all paths, and so fields listed under <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> may no longer be updated until <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code>Py_InitializeFromConfig()</code></a> is called.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyConfig_Clear">
<code>void PyConfig_Clear(PyConfig *config)</code> </dt> <dd>
<p>Release configuration memory.</p> </dd>
</dl> <p>Most <code>PyConfig</code> methods <a class="reference internal" href="#c-preinit"><span class="std std-ref">preinitialize Python</span></a> if needed. In that case, the Python preinitialization configuration (<a class="reference internal" href="#c.PyPreConfig" title="PyPreConfig"><code>PyPreConfig</code></a>) in based on the <a class="reference internal" href="#c.PyConfig" title="PyConfig"><code>PyConfig</code></a>. If configuration fields which are in common with <a class="reference internal" href="#c.PyPreConfig" title="PyPreConfig"><code>PyPreConfig</code></a> are tuned, they must be set before calling a <a class="reference internal" href="#c.PyConfig" title="PyConfig"><code>PyConfig</code></a> method:</p> <ul class="simple"> <li><a class="reference internal" href="#c.PyConfig.dev_mode" title="PyConfig.dev_mode"><code>PyConfig.dev_mode</code></a></li> <li><a class="reference internal" href="#c.PyConfig.isolated" title="PyConfig.isolated"><code>PyConfig.isolated</code></a></li> <li><a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a></li> <li><a class="reference internal" href="#c.PyConfig.use_environment" title="PyConfig.use_environment"><code>PyConfig.use_environment</code></a></li> </ul> <p>Moreover, if <a class="reference internal" href="#c.PyConfig_SetArgv" title="PyConfig_SetArgv"><code>PyConfig_SetArgv()</code></a> or <a class="reference internal" href="#c.PyConfig_SetBytesArgv" title="PyConfig_SetBytesArgv"><code>PyConfig_SetBytesArgv()</code></a> is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>parse_argv</code></a> is non-zero).</p> <p>The caller of these methods is responsible to handle exceptions (error or exit) using <code>PyStatus_Exception()</code> and <code>Py_ExitStatusException()</code>.</p> <p>Structure fields:</p> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.argv">
<code>PyWideStringList argv</code> </dt> <dd>
<p>Command line arguments: <a class="reference internal" href="../library/sys#sys.argv" title="sys.argv"><code>sys.argv</code></a>.</p> <p>Set <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>parse_argv</code></a> to <code>1</code> to parse <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> the same way the regular Python parses Python command line arguments and then to strip Python arguments from <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a>.</p> <p>If <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> is empty, an empty string is added to ensure that <a class="reference internal" href="../library/sys#sys.argv" title="sys.argv"><code>sys.argv</code></a> always exists and is never empty.</p> <p>Default: <code>NULL</code>.</p> <p>See also the <a class="reference internal" href="#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code>orig_argv</code></a> member.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.safe_path">
<code>int safe_path</code> </dt> <dd>
<p>If equals to zero, <code>Py_RunMain()</code> prepends a potentially unsafe path to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a> at startup:</p> <ul class="simple"> <li>If <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv[0]</code></a> is equal to <code>L"-m"</code> (<code>python -m module</code>), prepend the current working directory.</li> <li>If running a script (<code>python script.py</code>), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.</li> <li>Otherwise (<code>python -c code</code> and <code>python</code>), prepend an empty string, which means the current working directory.</li> </ul> <p>Set to <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-P"><code>-P</code></a> command line option and the <span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONSAFEPATH"><code>PYTHONSAFEPATH</code></a> environment variable.</p> <p>Default: <code>0</code> in Python config, <code>1</code> in isolated config.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.base_exec_prefix">
<code>wchar_t *base_exec_prefix</code> </dt> <dd>
<p><a class="reference internal" href="../library/sys#sys.base_exec_prefix" title="sys.base_exec_prefix"><code>sys.base_exec_prefix</code></a>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.base_executable">
<code>wchar_t *base_executable</code> </dt> <dd>
<p>Python base executable: <code>sys._base_executable</code>.</p> <p>Set by the <span class="target" id="index-4"></span><code>__PYVENV_LAUNCHER__</code> environment variable.</p> <p>Set from <a class="reference internal" href="#c.PyConfig.executable" title="PyConfig.executable"><code>PyConfig.executable</code></a> if <code>NULL</code>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.base_prefix">
<code>wchar_t *base_prefix</code> </dt> <dd>
<p><a class="reference internal" href="../library/sys#sys.base_prefix" title="sys.base_prefix"><code>sys.base_prefix</code></a>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.buffered_stdio">
<code>int buffered_stdio</code> </dt> <dd>
<p>If equals to <code>0</code> and <a class="reference internal" href="#c.PyConfig.configure_c_stdio" title="PyConfig.configure_c_stdio"><code>configure_c_stdio</code></a> is non-zero, disable buffering on the C streams stdout and stderr.</p> <p>Set to <code>0</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-u"><code>-u</code></a> command line option and the <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONUNBUFFERED"><code>PYTHONUNBUFFERED</code></a> environment variable.</p> <p>stdin is always opened in buffered mode.</p> <p>Default: <code>1</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.bytes_warning">
<code>int bytes_warning</code> </dt> <dd>
<p>If equals to <code>1</code>, issue a warning when comparing <a class="reference internal" href="../library/stdtypes#bytes" title="bytes"><code>bytes</code></a> or <a class="reference internal" href="../library/stdtypes#bytearray" title="bytearray"><code>bytearray</code></a> with <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str</code></a>, or comparing <a class="reference internal" href="../library/stdtypes#bytes" title="bytes"><code>bytes</code></a> with <a class="reference internal" href="../library/functions#int" title="int"><code>int</code></a>.</p> <p>If equal or greater to <code>2</code>, raise a <a class="reference internal" href="../library/exceptions#BytesWarning" title="BytesWarning"><code>BytesWarning</code></a> exception in these cases.</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-b"><code>-b</code></a> command line option.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.warn_default_encoding">
<code>int warn_default_encoding</code> </dt> <dd>
<p>If non-zero, emit a <a class="reference internal" href="../library/exceptions#EncodingWarning" title="EncodingWarning"><code>EncodingWarning</code></a> warning when <a class="reference internal" href="../library/io#io.TextIOWrapper" title="io.TextIOWrapper"><code>io.TextIOWrapper</code></a> uses its default encoding. See <a class="reference internal" href="../library/io#io-encoding-warning"><span class="std std-ref">Opt-in EncodingWarning</span></a> for details.</p> <p>Default: <code>0</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.code_debug_ranges">
<code>int code_debug_ranges</code> </dt> <dd>
<p>If equals to <code>0</code>, disables the inclusion of the end line and column mappings in code objects. Also disables traceback printing carets to specific error locations.</p> <p>Set to <code>0</code> by the <span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONNODEBUGRANGES"><code>PYTHONNODEBUGRANGES</code></a> environment variable and by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X no_debug_ranges</code></a> command line option.</p> <p>Default: <code>1</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.check_hash_pycs_mode">
<code>wchar_t *check_hash_pycs_mode</code> </dt> <dd>
<p>Control the validation behavior of hash-based <code>.pyc</code> files: value of the <a class="reference internal" href="../using/cmdline#cmdoption-check-hash-based-pycs"><code>--check-hash-based-pycs</code></a> command line option.</p> <p>Valid values:</p> <ul class="simple"> <li>
<code>L"always"</code>: Hash the source file for invalidation regardless of value of the ‘check_source’ flag.</li> <li>
<code>L"never"</code>: Assume that hash-based pycs always are valid.</li> <li>
<code>L"default"</code>: The ‘check_source’ flag in hash-based pycs determines invalidation.</li> </ul> <p>Default: <code>L"default"</code>.</p> <p>See also <span class="target" id="index-7"></span><a class="pep reference external" href="https://peps.python.org/pep-0552/"><strong>PEP 552</strong></a> “Deterministic pycs”.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.configure_c_stdio">
<code>int configure_c_stdio</code> </dt> <dd>
<p>If non-zero, configure C standard streams:</p> <ul class="simple"> <li>On Windows, set the binary mode (<code>O_BINARY</code>) on stdin, stdout and stderr.</li> <li>If <a class="reference internal" href="#c.PyConfig.buffered_stdio" title="PyConfig.buffered_stdio"><code>buffered_stdio</code></a> equals zero, disable buffering of stdin, stdout and stderr streams.</li> <li>If <a class="reference internal" href="#c.PyConfig.interactive" title="PyConfig.interactive"><code>interactive</code></a> is non-zero, enable stream buffering on stdin and stdout (only stdout on Windows).</li> </ul> <p>Default: <code>1</code> in Python config, <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.dev_mode">
<code>int dev_mode</code> </dt> <dd>
<p>If non-zero, enable the <a class="reference internal" href="../library/devmode#devmode"><span class="std std-ref">Python Development Mode</span></a>.</p> <p>Set to <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X dev</code></a> option and the <span class="target" id="index-8"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONDEVMODE"><code>PYTHONDEVMODE</code></a> environment variable.</p> <p>Default: <code>-1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.dump_refs">
<code>int dump_refs</code> </dt> <dd>
<p>Dump Python references?</p> <p>If non-zero, dump all objects which are still alive at exit.</p> <p>Set to <code>1</code> by the <span class="target" id="index-9"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONDUMPREFS"><code>PYTHONDUMPREFS</code></a> environment variable.</p> <p>Need a special build of Python with the <code>Py_TRACE_REFS</code> macro defined: see the <a class="reference internal" href="../using/configure#cmdoption-with-trace-refs"><code>configure --with-trace-refs option</code></a>.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.exec_prefix">
<code>wchar_t *exec_prefix</code> </dt> <dd>
<p>The site-specific directory prefix where the platform-dependent Python files are installed: <a class="reference internal" href="../library/sys#sys.exec_prefix" title="sys.exec_prefix"><code>sys.exec_prefix</code></a>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.executable">
<code>wchar_t *executable</code> </dt> <dd>
<p>The absolute path of the executable binary for the Python interpreter: <a class="reference internal" href="../library/sys#sys.executable" title="sys.executable"><code>sys.executable</code></a>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.faulthandler">
<code>int faulthandler</code> </dt> <dd>
<p>Enable faulthandler?</p> <p>If non-zero, call <a class="reference internal" href="../library/faulthandler#faulthandler.enable" title="faulthandler.enable"><code>faulthandler.enable()</code></a> at startup.</p> <p>Set to <code>1</code> by <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X faulthandler</code></a> and the <span class="target" id="index-10"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONFAULTHANDLER"><code>PYTHONFAULTHANDLER</code></a> environment variable.</p> <p>Default: <code>-1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.filesystem_encoding">
<code>wchar_t *filesystem_encoding</code> </dt> <dd>
<p><a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">Filesystem encoding</span></a>: <a class="reference internal" href="../library/sys#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code>sys.getfilesystemencoding()</code></a>.</p> <p>On macOS, Android and VxWorks: use <code>"utf-8"</code> by default.</p> <p>On Windows: use <code>"utf-8"</code> by default, or <code>"mbcs"</code> if <a class="reference internal" href="#c.PyPreConfig.legacy_windows_fs_encoding" title="PyPreConfig.legacy_windows_fs_encoding"><code>legacy_windows_fs_encoding</code></a> of <a class="reference internal" href="#c.PyPreConfig" title="PyPreConfig"><code>PyPreConfig</code></a> is non-zero.</p> <p>Default encoding on other platforms:</p> <ul class="simple"> <li>
<code>"utf-8"</code> if <a class="reference internal" href="#c.PyPreConfig.utf8_mode" title="PyPreConfig.utf8_mode"><code>PyPreConfig.utf8_mode</code></a> is non-zero.</li> <li>
<code>"ascii"</code> if Python detects that <code>nl_langinfo(CODESET)</code> announces the ASCII encoding, whereas the <code>mbstowcs()</code> function decodes from a different encoding (usually Latin1).</li> <li>
<code>"utf-8"</code> if <code>nl_langinfo(CODESET)</code> returns an empty string.</li> <li>Otherwise, use the <a class="reference internal" href="../glossary#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>: <code>nl_langinfo(CODESET)</code> result.</li> </ul> <p>At Python startup, the encoding name is normalized to the Python codec name. For example, <code>"ANSI_X3.4-1968"</code> is replaced with <code>"ascii"</code>.</p> <p>See also the <a class="reference internal" href="#c.PyConfig.filesystem_errors" title="PyConfig.filesystem_errors"><code>filesystem_errors</code></a> member.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.filesystem_errors">
<code>wchar_t *filesystem_errors</code> </dt> <dd>
<p><a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">Filesystem error handler</span></a>: <a class="reference internal" href="../library/sys#sys.getfilesystemencodeerrors" title="sys.getfilesystemencodeerrors"><code>sys.getfilesystemencodeerrors()</code></a>.</p> <p>On Windows: use <code>"surrogatepass"</code> by default, or <code>"replace"</code> if <a class="reference internal" href="#c.PyPreConfig.legacy_windows_fs_encoding" title="PyPreConfig.legacy_windows_fs_encoding"><code>legacy_windows_fs_encoding</code></a> of <a class="reference internal" href="#c.PyPreConfig" title="PyPreConfig"><code>PyPreConfig</code></a> is non-zero.</p> <p>On other platforms: use <code>"surrogateescape"</code> by default.</p> <p>Supported error handlers:</p> <ul class="simple"> <li><code>"strict"</code></li> <li><code>"surrogateescape"</code></li> <li>
<code>"surrogatepass"</code> (only supported with the UTF-8 encoding)</li> </ul> <p>See also the <a class="reference internal" href="#c.PyConfig.filesystem_encoding" title="PyConfig.filesystem_encoding"><code>filesystem_encoding</code></a> member.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.hash_seed">
<code>unsigned long hash_seed</code> </dt> <dd></dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.use_hash_seed">
<code>int use_hash_seed</code> </dt> <dd>
<p>Randomized hash function seed.</p> <p>If <a class="reference internal" href="#c.PyConfig.use_hash_seed" title="PyConfig.use_hash_seed"><code>use_hash_seed</code></a> is zero, a seed is chosen randomly at Python startup, and <a class="reference internal" href="#c.PyConfig.hash_seed" title="PyConfig.hash_seed"><code>hash_seed</code></a> is ignored.</p> <p>Set by the <span class="target" id="index-11"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONHASHSEED"><code>PYTHONHASHSEED</code></a> environment variable.</p> <p>Default <em>use_hash_seed</em> value: <code>-1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.home">
<code>wchar_t *home</code> </dt> <dd>
<p>Python home directory.</p> <p>If <a class="reference internal" href="init#c.Py_SetPythonHome" title="Py_SetPythonHome"><code>Py_SetPythonHome()</code></a> has been called, use its argument if it is not <code>NULL</code>.</p> <p>Set by the <span class="target" id="index-12"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONHOME"><code>PYTHONHOME</code></a> environment variable.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> input.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.import_time">
<code>int import_time</code> </dt> <dd>
<p>If non-zero, profile import time.</p> <p>Set the <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X importtime</code></a> option and the <span class="target" id="index-13"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPROFILEIMPORTTIME"><code>PYTHONPROFILEIMPORTTIME</code></a> environment variable.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.inspect">
<code>int inspect</code> </dt> <dd>
<p>Enter interactive mode after executing a script or a command.</p> <p>If greater than <code>0</code>, 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 <a class="reference internal" href="../library/sys#sys.stdin" title="sys.stdin"><code>sys.stdin</code></a> does not appear to be a terminal.</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-i"><code>-i</code></a> command line option. Set to <code>1</code> if the <span class="target" id="index-14"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONINSPECT"><code>PYTHONINSPECT</code></a> environment variable is non-empty.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.install_signal_handlers">
<code>int install_signal_handlers</code> </dt> <dd>
<p>Install Python signal handlers?</p> <p>Default: <code>1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.interactive">
<code>int interactive</code> </dt> <dd>
<p>If greater than <code>0</code>, enable the interactive mode (REPL).</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-i"><code>-i</code></a> command line option.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.int_max_str_digits">
<code>int int_max_str_digits</code> </dt> <dd>
<p>Configures the <a class="reference internal" href="../library/stdtypes#int-max-str-digits"><span class="std std-ref">integer string conversion length limitation</span></a>. An initial value of <code>-1</code> means the value will be taken from the command line or environment or otherwise default to 4300 (<a class="reference internal" href="../library/sys#sys.int_info.default_max_str_digits" title="sys.int_info.default_max_str_digits"><code>sys.int_info.default_max_str_digits</code></a>). A value of <code>0</code> disables the limitation. Values greater than zero but less than 640 (<a class="reference internal" href="../library/sys#sys.int_info.str_digits_check_threshold" title="sys.int_info.str_digits_check_threshold"><code>sys.int_info.str_digits_check_threshold</code></a>) are unsupported and will produce an error.</p> <p>Configured by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X int_max_str_digits</code></a> command line flag or the <span class="target" id="index-15"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONINTMAXSTRDIGITS"><code>PYTHONINTMAXSTRDIGITS</code></a> environment variable.</p> <p>Default: <code>-1</code> in Python mode. 4300 (<a class="reference internal" href="../library/sys#sys.int_info.default_max_str_digits" title="sys.int_info.default_max_str_digits"><code>sys.int_info.default_max_str_digits</code></a>) in isolated mode.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.isolated">
<code>int isolated</code> </dt> <dd>
<p>If greater than <code>0</code>, enable isolated mode:</p> <ul class="simple"> <li>Set <a class="reference internal" href="#c.PyConfig.safe_path" title="PyConfig.safe_path"><code>safe_path</code></a> to <code>1</code>: don’t prepend a potentially unsafe path to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a> at Python startup, such as the current directory, the script’s directory or an empty string.</li> <li>Set <a class="reference internal" href="#c.PyConfig.use_environment" title="PyConfig.use_environment"><code>use_environment</code></a> to <code>0</code>: ignore <code>PYTHON</code> environment variables.</li> <li>Set <a class="reference internal" href="#c.PyConfig.user_site_directory" title="PyConfig.user_site_directory"><code>user_site_directory</code></a> to <code>0</code>: don’t add the user site directory to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</li> <li>Python REPL doesn’t import <a class="reference internal" href="../library/readline#module-readline" title="readline: GNU readline support for Python. (Unix)"><code>readline</code></a> nor enable default readline configuration on interactive prompts.</li> </ul> <p>Set to <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-I"><code>-I</code></a> command line option.</p> <p>Default: <code>0</code> in Python mode, <code>1</code> in isolated mode.</p> <p>See also the <a class="reference internal" href="#init-isolated-conf"><span class="std std-ref">Isolated Configuration</span></a> and <a class="reference internal" href="#c.PyPreConfig.isolated" title="PyPreConfig.isolated"><code>PyPreConfig.isolated</code></a>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.legacy_windows_stdio">
<code>int legacy_windows_stdio</code> </dt> <dd>
<p>If non-zero, use <a class="reference internal" href="../library/io#io.FileIO" title="io.FileIO"><code>io.FileIO</code></a> instead of <code>io._WindowsConsoleIO</code> for <a class="reference internal" href="../library/sys#sys.stdin" title="sys.stdin"><code>sys.stdin</code></a>, <a class="reference internal" href="../library/sys#sys.stdout" title="sys.stdout"><code>sys.stdout</code></a> and <a class="reference internal" href="../library/sys#sys.stderr" title="sys.stderr"><code>sys.stderr</code></a>.</p> <p>Set to <code>1</code> if the <span class="target" id="index-16"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONLEGACYWINDOWSSTDIO"><code>PYTHONLEGACYWINDOWSSTDIO</code></a> environment variable is set to a non-empty string.</p> <p>Only available on Windows. <code>#ifdef MS_WINDOWS</code> macro can be used for Windows specific code.</p> <p>Default: <code>0</code>.</p> <p>See also the <span class="target" id="index-17"></span><a class="pep reference external" href="https://peps.python.org/pep-0528/"><strong>PEP 528</strong></a> (Change Windows console encoding to UTF-8).</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.malloc_stats">
<code>int malloc_stats</code> </dt> <dd>
<p>If non-zero, dump statistics on <a class="reference internal" href="memory#pymalloc"><span class="std std-ref">Python pymalloc memory allocator</span></a> at exit.</p> <p>Set to <code>1</code> by the <span class="target" id="index-18"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONMALLOCSTATS"><code>PYTHONMALLOCSTATS</code></a> environment variable.</p> <p>The option is ignored if Python is <a class="reference internal" href="../using/configure#cmdoption-without-pymalloc"><code>configured using
the --without-pymalloc option</code></a>.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.platlibdir">
<code>wchar_t *platlibdir</code> </dt> <dd>
<p>Platform library directory name: <a class="reference internal" href="../library/sys#sys.platlibdir" title="sys.platlibdir"><code>sys.platlibdir</code></a>.</p> <p>Set by the <span class="target" id="index-19"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPLATLIBDIR"><code>PYTHONPLATLIBDIR</code></a> environment variable.</p> <p>Default: value of the <code>PLATLIBDIR</code> macro which is set by the <a class="reference internal" href="../using/configure#cmdoption-with-platlibdir"><code>configure --with-platlibdir option</code></a> (default: <code>"lib"</code>, or <code>"DLLs"</code> on Windows).</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> input.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>This macro is now used on Windows to locate the standard library extension modules, typically under <code>DLLs</code>. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.</p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.pythonpath_env">
<code>wchar_t *pythonpath_env</code> </dt> <dd>
<p>Module search paths (<a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>) as a string separated by <code>DELIM</code> (<a class="reference internal" href="../library/os#os.pathsep" title="os.pathsep"><code>os.pathsep</code></a>).</p> <p>Set by the <span class="target" id="index-20"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPATH"><code>PYTHONPATH</code></a> environment variable.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> input.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.module_search_paths">
<code>PyWideStringList module_search_paths</code> </dt> <dd></dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.module_search_paths_set">
<code>int module_search_paths_set</code> </dt> <dd>
<p>Module search paths: <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</p> <p>If <a class="reference internal" href="#c.PyConfig.module_search_paths_set" title="PyConfig.module_search_paths_set"><code>module_search_paths_set</code></a> is equal to <code>0</code>, <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code>Py_InitializeFromConfig()</code></a> will replace <a class="reference internal" href="#c.PyConfig.module_search_paths" title="PyConfig.module_search_paths"><code>module_search_paths</code></a> and sets <a class="reference internal" href="#c.PyConfig.module_search_paths_set" title="PyConfig.module_search_paths_set"><code>module_search_paths_set</code></a> to <code>1</code>.</p> <p>Default: empty list (<code>module_search_paths</code>) and <code>0</code> (<code>module_search_paths_set</code>).</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.optimization_level">
<code>int optimization_level</code> </dt> <dd>
<p>Compilation optimization level:</p> <ul class="simple"> <li>
<code>0</code>: Peephole optimizer, set <code>__debug__</code> to <code>True</code>.</li> <li>
<code>1</code>: Level 0, remove assertions, set <code>__debug__</code> to <code>False</code>.</li> <li>
<code>2</code>: Level 1, strip docstrings.</li> </ul> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-O"><code>-O</code></a> command line option. Set to the <span class="target" id="index-21"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONOPTIMIZE"><code>PYTHONOPTIMIZE</code></a> environment variable value.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.orig_argv">
<code>PyWideStringList orig_argv</code> </dt> <dd>
<p>The list of the original command line arguments passed to the Python executable: <a class="reference internal" href="../library/sys#sys.orig_argv" title="sys.orig_argv"><code>sys.orig_argv</code></a>.</p> <p>If <a class="reference internal" href="#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code>orig_argv</code></a> list is empty and <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> is not a list only containing an empty string, <a class="reference internal" href="#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a> copies <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> into <a class="reference internal" href="#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code>orig_argv</code></a> before modifying <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> (if <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>parse_argv</code></a> is non-zero).</p> <p>See also the <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> member and the <a class="reference internal" href="#c.Py_GetArgcArgv" title="Py_GetArgcArgv"><code>Py_GetArgcArgv()</code></a> function.</p> <p>Default: empty list.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.parse_argv">
<code>int parse_argv</code> </dt> <dd>
<p>Parse command line arguments?</p> <p>If equals to <code>1</code>, parse <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> the same way the regular Python parses <a class="reference internal" href="../using/cmdline#using-on-cmdline"><span class="std std-ref">command line arguments</span></a>, and strip Python arguments from <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a>.</p> <p>The <a class="reference internal" href="#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a> function only parses <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a> arguments once: <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a> is set to <code>2</code> after arguments are parsed. Since Python arguments are strippped from <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a>, parsing arguments twice would parse the application options as Python options.</p> <p>Default: <code>1</code> in Python mode, <code>0</code> in isolated mode.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a> arguments are now only parsed if <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>PyConfig.parse_argv</code></a> equals to <code>1</code>.</p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.parser_debug">
<code>int parser_debug</code> </dt> <dd>
<p>Parser debug mode. If greater than <code>0</code>, turn on parser debugging output (for expert only, depending on compilation options).</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-d"><code>-d</code></a> command line option. Set to the <span class="target" id="index-22"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONDEBUG"><code>PYTHONDEBUG</code></a> environment variable value.</p> <p>Need a <a class="reference internal" href="../using/configure#debug-build"><span class="std std-ref">debug build of Python</span></a> (the <code>Py_DEBUG</code> macro must be defined).</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.pathconfig_warnings">
<code>int pathconfig_warnings</code> </dt> <dd>
<p>If non-zero, calculation of path configuration is allowed to log warnings into <code>stderr</code>. If equals to <code>0</code>, suppress these warnings.</p> <p>Default: <code>1</code> in Python mode, <code>0</code> in isolated mode.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> input.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Now also applies on Windows.</p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.prefix">
<code>wchar_t *prefix</code> </dt> <dd>
<p>The site-specific directory prefix where the platform independent Python files are installed: <a class="reference internal" href="../library/sys#sys.prefix" title="sys.prefix"><code>sys.prefix</code></a>.</p> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> output.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.program_name">
<code>wchar_t *program_name</code> </dt> <dd>
<p>Program name used to initialize <a class="reference internal" href="#c.PyConfig.executable" title="PyConfig.executable"><code>executable</code></a> and in early error messages during Python initialization.</p> <ul class="simple"> <li>If <code>Py_SetProgramName()</code> has been called, use its argument.</li> <li>On macOS, use <span class="target" id="index-23"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONEXECUTABLE"><code>PYTHONEXECUTABLE</code></a> environment variable if set.</li> <li>If the <code>WITH_NEXT_FRAMEWORK</code> macro is defined, use <span class="target" id="index-24"></span><code>__PYVENV_LAUNCHER__</code> environment variable if set.</li> <li>Use <code>argv[0]</code> of <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> if available and non-empty.</li> <li>Otherwise, use <code>L"python"</code> on Windows, or <code>L"python3"</code> on other platforms.</li> </ul> <p>Default: <code>NULL</code>.</p> <p>Part of the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Python Path Configuration</span></a> input.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.pycache_prefix">
<code>wchar_t *pycache_prefix</code> </dt> <dd>
<p>Directory where cached <code>.pyc</code> files are written: <a class="reference internal" href="../library/sys#sys.pycache_prefix" title="sys.pycache_prefix"><code>sys.pycache_prefix</code></a>.</p> <p>Set by the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X pycache_prefix=PATH</code></a> command line option and the <span class="target" id="index-25"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPYCACHEPREFIX"><code>PYTHONPYCACHEPREFIX</code></a> environment variable.</p> <p>If <code>NULL</code>, <a class="reference internal" href="../library/sys#sys.pycache_prefix" title="sys.pycache_prefix"><code>sys.pycache_prefix</code></a> is set to <code>None</code>.</p> <p>Default: <code>NULL</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.quiet">
<code>int quiet</code> </dt> <dd>
<p>Quiet mode. If greater than <code>0</code>, don’t display the copyright and version at Python startup in interactive mode.</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-q"><code>-q</code></a> command line option.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.run_command">
<code>wchar_t *run_command</code> </dt> <dd>
<p>Value of the <a class="reference internal" href="../using/cmdline#cmdoption-c"><code>-c</code></a> command line option.</p> <p>Used by <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a>.</p> <p>Default: <code>NULL</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.run_filename">
<code>wchar_t *run_filename</code> </dt> <dd>
<p>Filename passed on the command line: trailing command line argument without <a class="reference internal" href="../using/cmdline#cmdoption-c"><code>-c</code></a> or <a class="reference internal" href="../using/cmdline#cmdoption-m"><code>-m</code></a>. It is used by the <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a> function.</p> <p>For example, it is set to <code>script.py</code> by the <code>python3 script.py arg</code> command line.</p> <p>See also the <a class="reference internal" href="#c.PyConfig.skip_source_first_line" title="PyConfig.skip_source_first_line"><code>PyConfig.skip_source_first_line</code></a> option.</p> <p>Default: <code>NULL</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.run_module">
<code>wchar_t *run_module</code> </dt> <dd>
<p>Value of the <a class="reference internal" href="../using/cmdline#cmdoption-m"><code>-m</code></a> command line option.</p> <p>Used by <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a>.</p> <p>Default: <code>NULL</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.show_ref_count">
<code>int show_ref_count</code> </dt> <dd>
<p>Show total reference count at exit (excluding immortal objects)?</p> <p>Set to <code>1</code> by <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X showrefcount</code></a> command line option.</p> <p>Need a <a class="reference internal" href="../using/configure#debug-build"><span class="std std-ref">debug build of Python</span></a> (the <code>Py_REF_DEBUG</code> macro must be defined).</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.site_import">
<code>int site_import</code> </dt> <dd>
<p>Import the <a class="reference internal" href="../library/site#module-site" title="site: Module responsible for site-specific configuration."><code>site</code></a> module at startup?</p> <p>If equal to zero, disable the import of the module site and the site-dependent manipulations of <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a> that it entails.</p> <p>Also disable these manipulations if the <a class="reference internal" href="../library/site#module-site" title="site: Module responsible for site-specific configuration."><code>site</code></a> module is explicitly imported later (call <a class="reference internal" href="../library/site#site.main" title="site.main"><code>site.main()</code></a> if you want them to be triggered).</p> <p>Set to <code>0</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-S"><code>-S</code></a> command line option.</p> <p><a class="reference internal" href="../library/sys#sys.flags" title="sys.flags"><code>sys.flags.no_site</code></a> is set to the inverted value of <a class="reference internal" href="#c.PyConfig.site_import" title="PyConfig.site_import"><code>site_import</code></a>.</p> <p>Default: <code>1</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.skip_source_first_line">
<code>int skip_source_first_line</code> </dt> <dd>
<p>If non-zero, skip the first line of the <a class="reference internal" href="#c.PyConfig.run_filename" title="PyConfig.run_filename"><code>PyConfig.run_filename</code></a> source.</p> <p>It allows the usage of non-Unix forms of <code>#!cmd</code>. This is intended for a DOS specific hack only.</p> <p>Set to <code>1</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-x"><code>-x</code></a> command line option.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.stdio_encoding">
<code>wchar_t *stdio_encoding</code> </dt> <dd></dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.stdio_errors">
<code>wchar_t *stdio_errors</code> </dt> <dd>
<p>Encoding and encoding errors of <a class="reference internal" href="../library/sys#sys.stdin" title="sys.stdin"><code>sys.stdin</code></a>, <a class="reference internal" href="../library/sys#sys.stdout" title="sys.stdout"><code>sys.stdout</code></a> and <a class="reference internal" href="../library/sys#sys.stderr" title="sys.stderr"><code>sys.stderr</code></a> (but <a class="reference internal" href="../library/sys#sys.stderr" title="sys.stderr"><code>sys.stderr</code></a> always uses <code>"backslashreplace"</code> error handler).</p> <p>If <a class="reference internal" href="init#c.Py_SetStandardStreamEncoding" title="Py_SetStandardStreamEncoding"><code>Py_SetStandardStreamEncoding()</code></a> has been called, use its <em>error</em> and <em>errors</em> arguments if they are not <code>NULL</code>.</p> <p>Use the <span class="target" id="index-26"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONIOENCODING"><code>PYTHONIOENCODING</code></a> environment variable if it is non-empty.</p> <p>Default encoding:</p> <ul class="simple"> <li>
<code>"UTF-8"</code> if <a class="reference internal" href="#c.PyPreConfig.utf8_mode" title="PyPreConfig.utf8_mode"><code>PyPreConfig.utf8_mode</code></a> is non-zero.</li> <li>Otherwise, use the <a class="reference internal" href="../glossary#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a>.</li> </ul> <p>Default error handler:</p> <ul class="simple"> <li>On Windows: use <code>"surrogateescape"</code>.</li> <li>
<code>"surrogateescape"</code> if <a class="reference internal" href="#c.PyPreConfig.utf8_mode" title="PyPreConfig.utf8_mode"><code>PyPreConfig.utf8_mode</code></a> is non-zero, or if the LC_CTYPE locale is “C” or “POSIX”.</li> <li>
<code>"strict"</code> otherwise.</li> </ul> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.tracemalloc">
<code>int tracemalloc</code> </dt> <dd>
<p>Enable tracemalloc?</p> <p>If non-zero, call <a class="reference internal" href="../library/tracemalloc#tracemalloc.start" title="tracemalloc.start"><code>tracemalloc.start()</code></a> at startup.</p> <p>Set by <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X tracemalloc=N</code></a> command line option and by the <span class="target" id="index-27"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONTRACEMALLOC"><code>PYTHONTRACEMALLOC</code></a> environment variable.</p> <p>Default: <code>-1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.perf_profiling">
<code>int perf_profiling</code> </dt> <dd>
<p>Enable compatibility mode with the perf profiler?</p> <p>If non-zero, initialize the perf trampoline. See <a class="reference internal" href="../howto/perf_profiling#perf-profiling"><span class="std std-ref">Python support for the Linux perf profiler</span></a> for more information.</p> <p>Set by <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X perf</code></a> command line option and by the <span class="target" id="index-28"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONPERFSUPPORT"><code>PYTHONPERFSUPPORT</code></a> environment variable.</p> <p>Default: <code>-1</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.use_environment">
<code>int use_environment</code> </dt> <dd>
<p>Use <a class="reference internal" href="../using/cmdline#using-on-envvars"><span class="std std-ref">environment variables</span></a>?</p> <p>If equals to zero, ignore the <a class="reference internal" href="../using/cmdline#using-on-envvars"><span class="std std-ref">environment variables</span></a>.</p> <p>Set to <code>0</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-E"><code>-E</code></a> environment variable.</p> <p>Default: <code>1</code> in Python config and <code>0</code> in isolated config.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.user_site_directory">
<code>int user_site_directory</code> </dt> <dd>
<p>If non-zero, add the user site directory to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</p> <p>Set to <code>0</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-s"><code>-s</code></a> and <a class="reference internal" href="../using/cmdline#cmdoption-I"><code>-I</code></a> command line options.</p> <p>Set to <code>0</code> by the <span class="target" id="index-29"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONNOUSERSITE"><code>PYTHONNOUSERSITE</code></a> environment variable.</p> <p>Default: <code>1</code> in Python mode, <code>0</code> in isolated mode.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.verbose">
<code>int verbose</code> </dt> <dd>
<p>Verbose mode. If greater than <code>0</code>, print a message each time a module is imported, showing the place (filename or built-in module) from which it is loaded.</p> <p>If greater than or equal to <code>2</code>, print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.</p> <p>Incremented by the <a class="reference internal" href="../using/cmdline#cmdoption-1"><code>-v</code></a> command line option.</p> <p>Set by the <span class="target" id="index-30"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONVERBOSE"><code>PYTHONVERBOSE</code></a> environment variable value.</p> <p>Default: <code>0</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.warnoptions">
<code>PyWideStringList warnoptions</code> </dt> <dd>
<p>Options of the <a class="reference internal" href="../library/warnings#module-warnings" title="warnings: Issue warning messages and control their disposition."><code>warnings</code></a> module to build warnings filters, lowest to highest priority: <a class="reference internal" href="../library/sys#sys.warnoptions" title="sys.warnoptions"><code>sys.warnoptions</code></a>.</p> <p>The <a class="reference internal" href="../library/warnings#module-warnings" title="warnings: Issue warning messages and control their disposition."><code>warnings</code></a> module adds <a class="reference internal" href="../library/sys#sys.warnoptions" title="sys.warnoptions"><code>sys.warnoptions</code></a> in the reverse order: the last <a class="reference internal" href="#c.PyConfig.warnoptions" title="PyConfig.warnoptions"><code>PyConfig.warnoptions</code></a> item becomes the first item of <code>warnings.filters</code> which is checked first (highest priority).</p> <p>The <a class="reference internal" href="../using/cmdline#cmdoption-W"><code>-W</code></a> command line options adds its value to <a class="reference internal" href="#c.PyConfig.warnoptions" title="PyConfig.warnoptions"><code>warnoptions</code></a>, it can be used multiple times.</p> <p>The <span class="target" id="index-31"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONWARNINGS"><code>PYTHONWARNINGS</code></a> environment variable can also be used to add warning options. Multiple options can be specified, separated by commas (<code>,</code>).</p> <p>Default: empty list.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.write_bytecode">
<code>int write_bytecode</code> </dt> <dd>
<p>If equal to <code>0</code>, Python won’t try to write <code>.pyc</code> files on the import of source modules.</p> <p>Set to <code>0</code> by the <a class="reference internal" href="../using/cmdline#cmdoption-B"><code>-B</code></a> command line option and the <span class="target" id="index-32"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONDONTWRITEBYTECODE"><code>PYTHONDONTWRITEBYTECODE</code></a> environment variable.</p> <p><a class="reference internal" href="../library/sys#sys.dont_write_bytecode" title="sys.dont_write_bytecode"><code>sys.dont_write_bytecode</code></a> is initialized to the inverted value of <a class="reference internal" href="#c.PyConfig.write_bytecode" title="PyConfig.write_bytecode"><code>write_bytecode</code></a>.</p> <p>Default: <code>1</code>.</p> </dd>
</dl> <dl class="c member"> <dt class="sig sig-object c" id="c.PyConfig.xoptions">
<code>PyWideStringList xoptions</code> </dt> <dd>
<p>Values of the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> command line options: <a class="reference internal" href="../library/sys#sys._xoptions" title="sys._xoptions"><code>sys._xoptions</code></a>.</p> <p>Default: empty list.</p> </dd>
</dl> </dd>
</dl> <p>If <a class="reference internal" href="#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code>parse_argv</code></a> is non-zero, <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a> arguments are parsed the same way the regular Python parses <a class="reference internal" href="../using/cmdline#using-on-cmdline"><span class="std std-ref">command line arguments</span></a>, and Python arguments are stripped from <a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>argv</code></a>.</p> <p>The <a class="reference internal" href="#c.PyConfig.xoptions" title="PyConfig.xoptions"><code>xoptions</code></a> options are parsed to set other options: see the <a class="reference internal" href="../using/cmdline#cmdoption-X"><code>-X</code></a> command line option.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The <code>show_alloc_count</code> field has been removed.</p> </div> </section> <section id="initialization-with-pyconfig"> <h2>Initialization with PyConfig</h2> <p>Function to initialize Python:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_InitializeFromConfig">
<code>PyStatus Py_InitializeFromConfig(const PyConfig *config)</code> </dt> <dd>
<p>Initialize Python from <em>config</em> configuration.</p> </dd>
</dl> <p>The caller is responsible to handle exceptions (error or exit) using <a class="reference internal" href="#c.PyStatus_Exception" title="PyStatus_Exception"><code>PyStatus_Exception()</code></a> and <a class="reference internal" href="#c.Py_ExitStatusException" title="Py_ExitStatusException"><code>Py_ExitStatusException()</code></a>.</p> <p>If <a class="reference internal" href="import#c.PyImport_FrozenModules" title="PyImport_FrozenModules"><code>PyImport_FrozenModules()</code></a>, <a class="reference internal" href="import#c.PyImport_AppendInittab" title="PyImport_AppendInittab"><code>PyImport_AppendInittab()</code></a> or <a class="reference internal" href="import#c.PyImport_ExtendInittab" title="PyImport_ExtendInittab"><code>PyImport_ExtendInittab()</code></a> are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times, <a class="reference internal" href="import#c.PyImport_AppendInittab" title="PyImport_AppendInittab"><code>PyImport_AppendInittab()</code></a> or <a class="reference internal" href="import#c.PyImport_ExtendInittab" title="PyImport_ExtendInittab"><code>PyImport_ExtendInittab()</code></a> must be called before each Python initialization.</p> <p>The current configuration (<code>PyConfig</code> type) is stored in <code>PyInterpreterState.config</code>.</p> <p>Example setting the program name:</p> <pre data-language="c">void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&amp;config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&amp;config, &amp;config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&amp;config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&amp;config);
    return;

exception:
    PyConfig_Clear(&amp;config);
    Py_ExitStatusException(status);
}
</pre> <p>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:</p> <pre data-language="c">PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&amp;config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&amp;config, &amp;config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&amp;config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* 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(&amp;config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) {
        goto done;
    }
    status = PyWideStringList_Append(&amp;config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&amp;config, &amp;config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&amp;config);

done:
    PyConfig_Clear(&amp;config);
    return status;
}
</pre> </section> <section id="isolated-configuration"> <span id="init-isolated-conf"></span><h2>Isolated Configuration</h2> <p><a class="reference internal" href="#c.PyPreConfig_InitIsolatedConfig" title="PyPreConfig_InitIsolatedConfig"><code>PyPreConfig_InitIsolatedConfig()</code></a> and <a class="reference internal" href="#c.PyConfig_InitIsolatedConfig" title="PyConfig_InitIsolatedConfig"><code>PyConfig_InitIsolatedConfig()</code></a> functions create a configuration to isolate Python from the system. For example, to embed Python into an application.</p> <p>This configuration ignores global configuration variables, environment variables, command line arguments (<a class="reference internal" href="#c.PyConfig.argv" title="PyConfig.argv"><code>PyConfig.argv</code></a> is not parsed) and user site directory. The C standard streams (ex: <code>stdout</code>) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed.</p> <p>Configuration files are still used with this configuration to determine paths that are unspecified. Ensure <a class="reference internal" href="#c.PyConfig.home" title="PyConfig.home"><code>PyConfig.home</code></a> is specified to avoid computing the default path configuration.</p> </section> <section id="python-configuration"> <span id="init-python-config"></span><h2>Python Configuration</h2> <p><a class="reference internal" href="#c.PyPreConfig_InitPythonConfig" title="PyPreConfig_InitPythonConfig"><code>PyPreConfig_InitPythonConfig()</code></a> and <a class="reference internal" href="#c.PyConfig_InitPythonConfig" title="PyConfig_InitPythonConfig"><code>PyConfig_InitPythonConfig()</code></a> functions create a configuration to build a customized Python which behaves as the regular Python.</p> <p>Environments variables and command line arguments are used to configure Python, whereas global configuration variables are ignored.</p> <p>This function enables C locale coercion (<span class="target" id="index-33"></span><a class="pep reference external" href="https://peps.python.org/pep-0538/"><strong>PEP 538</strong></a>) and <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a> (<span class="target" id="index-34"></span><a class="pep reference external" href="https://peps.python.org/pep-0540/"><strong>PEP 540</strong></a>) depending on the LC_CTYPE locale, <span class="target" id="index-35"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONUTF8"><code>PYTHONUTF8</code></a> and <span class="target" id="index-36"></span><a class="reference internal" href="../using/cmdline#envvar-PYTHONCOERCECLOCALE"><code>PYTHONCOERCECLOCALE</code></a> environment variables.</p> </section> <section id="python-path-configuration"> <span id="init-path-config"></span><h2>Python Path Configuration</h2> <p><a class="reference internal" href="#c.PyConfig" title="PyConfig"><code>PyConfig</code></a> contains multiple fields for the path configuration:</p> <ul class="simple"> <li>
<p>Path configuration inputs:</p> <ul> <li><a class="reference internal" href="#c.PyConfig.home" title="PyConfig.home"><code>PyConfig.home</code></a></li> <li><a class="reference internal" href="#c.PyConfig.platlibdir" title="PyConfig.platlibdir"><code>PyConfig.platlibdir</code></a></li> <li><a class="reference internal" href="#c.PyConfig.pathconfig_warnings" title="PyConfig.pathconfig_warnings"><code>PyConfig.pathconfig_warnings</code></a></li> <li><a class="reference internal" href="#c.PyConfig.program_name" title="PyConfig.program_name"><code>PyConfig.program_name</code></a></li> <li><a class="reference internal" href="#c.PyConfig.pythonpath_env" title="PyConfig.pythonpath_env"><code>PyConfig.pythonpath_env</code></a></li> <li>current working directory: to get absolute paths</li> <li>
<code>PATH</code> environment variable to get the program full path (from <a class="reference internal" href="#c.PyConfig.program_name" title="PyConfig.program_name"><code>PyConfig.program_name</code></a>)</li> <li>
<code>__PYVENV_LAUNCHER__</code> environment variable</li> <li>(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).</li> </ul> </li> <li>
<p>Path configuration output fields:</p> <ul> <li><a class="reference internal" href="#c.PyConfig.base_exec_prefix" title="PyConfig.base_exec_prefix"><code>PyConfig.base_exec_prefix</code></a></li> <li><a class="reference internal" href="#c.PyConfig.base_executable" title="PyConfig.base_executable"><code>PyConfig.base_executable</code></a></li> <li><a class="reference internal" href="#c.PyConfig.base_prefix" title="PyConfig.base_prefix"><code>PyConfig.base_prefix</code></a></li> <li><a class="reference internal" href="#c.PyConfig.exec_prefix" title="PyConfig.exec_prefix"><code>PyConfig.exec_prefix</code></a></li> <li><a class="reference internal" href="#c.PyConfig.executable" title="PyConfig.executable"><code>PyConfig.executable</code></a></li> <li>
<a class="reference internal" href="#c.PyConfig.module_search_paths_set" title="PyConfig.module_search_paths_set"><code>PyConfig.module_search_paths_set</code></a>, <a class="reference internal" href="#c.PyConfig.module_search_paths" title="PyConfig.module_search_paths"><code>PyConfig.module_search_paths</code></a>
</li> <li><a class="reference internal" href="#c.PyConfig.prefix" title="PyConfig.prefix"><code>PyConfig.prefix</code></a></li> </ul> </li> </ul> <p>If at least one “output field” is not set, Python calculates the path configuration to fill unset fields. If <a class="reference internal" href="#c.PyConfig.module_search_paths_set" title="PyConfig.module_search_paths_set"><code>module_search_paths_set</code></a> is equal to <code>0</code>, <a class="reference internal" href="#c.PyConfig.module_search_paths" title="PyConfig.module_search_paths"><code>module_search_paths</code></a> is overridden and <a class="reference internal" href="#c.PyConfig.module_search_paths_set" title="PyConfig.module_search_paths_set"><code>module_search_paths_set</code></a> is set to <code>1</code>.</p> <p>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. <code>module_search_paths</code> is considered as set if <code>module_search_paths_set</code> is set to <code>1</code>. In this case, <code>module_search_paths</code> will be used without modification.</p> <p>Set <a class="reference internal" href="#c.PyConfig.pathconfig_warnings" title="PyConfig.pathconfig_warnings"><code>pathconfig_warnings</code></a> to <code>0</code> to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).</p> <p>If <a class="reference internal" href="#c.PyConfig.base_prefix" title="PyConfig.base_prefix"><code>base_prefix</code></a> or <a class="reference internal" href="#c.PyConfig.base_exec_prefix" title="PyConfig.base_exec_prefix"><code>base_exec_prefix</code></a> fields are not set, they inherit their value from <a class="reference internal" href="#c.PyConfig.prefix" title="PyConfig.prefix"><code>prefix</code></a> and <a class="reference internal" href="#c.PyConfig.exec_prefix" title="PyConfig.exec_prefix"><code>exec_prefix</code></a> respectively.</p> <p><a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a> and <a class="reference internal" href="veryhigh#c.Py_Main" title="Py_Main"><code>Py_Main()</code></a> modify <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>:</p> <ul class="simple"> <li>If <a class="reference internal" href="#c.PyConfig.run_filename" title="PyConfig.run_filename"><code>run_filename</code></a> is set and is a directory which contains a <code>__main__.py</code> script, prepend <a class="reference internal" href="#c.PyConfig.run_filename" title="PyConfig.run_filename"><code>run_filename</code></a> to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</li> <li>
<p>If <a class="reference internal" href="#c.PyConfig.isolated" title="PyConfig.isolated"><code>isolated</code></a> is zero:</p> <ul> <li>If <a class="reference internal" href="#c.PyConfig.run_module" title="PyConfig.run_module"><code>run_module</code></a> is set, prepend the current directory to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>. Do nothing if the current directory cannot be read.</li> <li>If <a class="reference internal" href="#c.PyConfig.run_filename" title="PyConfig.run_filename"><code>run_filename</code></a> is set, prepend the directory of the filename to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</li> <li>Otherwise, prepend an empty string to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</li> </ul> </li> </ul> <p>If <a class="reference internal" href="#c.PyConfig.site_import" title="PyConfig.site_import"><code>site_import</code></a> is non-zero, <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a> can be modified by the <a class="reference internal" href="../library/site#module-site" title="site: Module responsible for site-specific configuration."><code>site</code></a> module. If <a class="reference internal" href="#c.PyConfig.user_site_directory" title="PyConfig.user_site_directory"><code>user_site_directory</code></a> is non-zero and the user’s site-package directory exists, the <a class="reference internal" href="../library/site#module-site" title="site: Module responsible for site-specific configuration."><code>site</code></a> module appends the user’s site-package directory to <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>.</p> <p>The following configuration files are used by the path configuration:</p> <ul class="simple"> <li><code>pyvenv.cfg</code></li> <li>
<code>._pth</code> file (ex: <code>python._pth</code>)</li> <li>
<code>pybuilddir.txt</code> (Unix only)</li> </ul> <p>If a <code>._pth</code> file is present:</p> <ul class="simple"> <li>Set <a class="reference internal" href="#c.PyConfig.isolated" title="PyConfig.isolated"><code>isolated</code></a> to <code>1</code>.</li> <li>Set <a class="reference internal" href="#c.PyConfig.use_environment" title="PyConfig.use_environment"><code>use_environment</code></a> to <code>0</code>.</li> <li>Set <a class="reference internal" href="#c.PyConfig.site_import" title="PyConfig.site_import"><code>site_import</code></a> to <code>0</code>.</li> <li>Set <a class="reference internal" href="#c.PyConfig.safe_path" title="PyConfig.safe_path"><code>safe_path</code></a> to <code>1</code>.</li> </ul> <p>The <code>__PYVENV_LAUNCHER__</code> environment variable is used to set <a class="reference internal" href="#c.PyConfig.base_executable" title="PyConfig.base_executable"><code>PyConfig.base_executable</code></a></p> </section> <section id="py-runmain"> <h2>Py_RunMain()</h2> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_RunMain">
<code>int Py_RunMain(void)</code> </dt> <dd>
<p>Execute the command (<a class="reference internal" href="#c.PyConfig.run_command" title="PyConfig.run_command"><code>PyConfig.run_command</code></a>), the script (<a class="reference internal" href="#c.PyConfig.run_filename" title="PyConfig.run_filename"><code>PyConfig.run_filename</code></a>) or the module (<a class="reference internal" href="#c.PyConfig.run_module" title="PyConfig.run_module"><code>PyConfig.run_module</code></a>) specified on the command line or in the configuration.</p> <p>By default and when if <a class="reference internal" href="../using/cmdline#cmdoption-i"><code>-i</code></a> option is used, run the REPL.</p> <p>Finally, finalizes Python and returns an exit status that can be passed to the <code>exit()</code> function.</p> </dd>
</dl> <p>See <a class="reference internal" href="#init-python-config"><span class="std std-ref">Python Configuration</span></a> for an example of customized Python always running in isolated mode using <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code>Py_RunMain()</code></a>.</p> </section> <section id="py-getargcargv"> <h2>Py_GetArgcArgv()</h2> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_GetArgcArgv">
<code>void Py_GetArgcArgv(int *argc, wchar_t ***argv)</code> </dt> <dd>
<p>Get the original command line arguments, before Python modified them.</p> <p>See also <a class="reference internal" href="#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code>PyConfig.orig_argv</code></a> member.</p> </dd>
</dl> </section> <section id="multi-phase-initialization-private-provisional-api"> <h2>Multi-Phase Initialization Private Provisional API</h2> <p>This section is a private provisional API introducing multi-phase initialization, the core feature of <span class="target" id="index-37"></span><a class="pep reference external" href="https://peps.python.org/pep-0432/"><strong>PEP 432</strong></a>:</p> <ul class="simple"> <li>
<p>“Core” initialization phase, “bare minimum Python”:</p> <ul> <li>Builtin types;</li> <li>Builtin exceptions;</li> <li>Builtin and frozen modules;</li> <li>The <a class="reference internal" href="../library/sys#module-sys" title="sys: Access system-specific parameters and functions."><code>sys</code></a> module is only partially initialized (ex: <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a> doesn’t exist yet).</li> </ul> </li> <li>
<p>“Main” initialization phase, Python is fully initialized:</p> <ul> <li>Install and configure <a class="reference internal" href="../library/importlib#module-importlib" title="importlib: The implementation of the import machinery."><code>importlib</code></a>;</li> <li>Apply the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Path Configuration</span></a>;</li> <li>Install signal handlers;</li> <li>Finish <a class="reference internal" href="../library/sys#module-sys" title="sys: Access system-specific parameters and functions."><code>sys</code></a> module initialization (ex: create <a class="reference internal" href="../library/sys#sys.stdout" title="sys.stdout"><code>sys.stdout</code></a> and <a class="reference internal" href="../library/sys#sys.path" title="sys.path"><code>sys.path</code></a>);</li> <li>Enable optional features like <a class="reference internal" href="../library/faulthandler#module-faulthandler" title="faulthandler: Dump the Python traceback."><code>faulthandler</code></a> and <a class="reference internal" href="../library/tracemalloc#module-tracemalloc" title="tracemalloc: Trace memory allocations."><code>tracemalloc</code></a>;</li> <li>Import the <a class="reference internal" href="../library/site#module-site" title="site: Module responsible for site-specific configuration."><code>site</code></a> module;</li> <li>etc.</li> </ul> </li> </ul> <p>Private provisional API:</p> <ul class="simple"> <li>
<code>PyConfig._init_main</code>: if set to <code>0</code>, <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code>Py_InitializeFromConfig()</code></a> stops at the “Core” initialization phase.</li> </ul> <dl class="c function"> <dt class="sig sig-object c" id="c._Py_InitializeMain">
<code>PyStatus _Py_InitializeMain(void)</code> </dt> <dd>
<p>Move to the “Main” initialization phase, finish the Python initialization.</p> </dd>
</dl> <p>No module is imported during the “Core” phase and the <code>importlib</code> module is not configured: the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Path Configuration</span></a> is only applied during the “Main” phase. It may allow to customize Python in Python to override or tune the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Path Configuration</span></a>, maybe install a custom <a class="reference internal" href="../library/sys#sys.meta_path" title="sys.meta_path"><code>sys.meta_path</code></a> importer or an import hook, etc.</p> <p>It may become possible to calculate the <a class="reference internal" href="#init-path-config"><span class="std std-ref">Path Configuration</span></a> in Python, after the Core phase and before the Main phase, which is one of the <span class="target" id="index-38"></span><a class="pep reference external" href="https://peps.python.org/pep-0432/"><strong>PEP 432</strong></a> motivation.</p> <p>The “Core” phase is not properly defined: what should be and what should not be available at this phase is not specified yet. The API is marked as private and provisional: the API can be modified or even be removed anytime until a proper public API is designed.</p> <p>Example running Python code between “Core” and “Main” initialization phases:</p> <pre data-language="c">void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&amp;config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&amp;config);
    PyConfig_Clear(&amp;config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res &lt; 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}
</pre> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/init_config.html" class="_attribution-link">https://docs.python.org/3.12/c-api/init_config.html</a>
  </p>
</div>