Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
sys_path_init.html487 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="The initialization of the sys.path module search path" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/sys_path_init.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="A module search path is initialized when Python starts. This module search path may be accessed at sys.path. The first entry in the module search path is the directory that contains the input scrip..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_sys_path_init_e00f095a.png" />15<meta property="og:image:alt" content="A module search path is initialized when Python starts. This module search path may be accessed at sys.path. The first entry in the module search path is the directory that contains the input scrip..." />16<meta name="description" content="A module search path is initialized when Python starts. This module search path may be accessed at sys.path. The first entry in the module search path is the directory that contains the input scrip..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>The initialization of the sys.path module search path &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="Python Language Services" href="language.html" />43    <link rel="prev" title="importlib.metadata – Accessing package metadata" href="importlib.metadata.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/sys_path_init.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#">The initialization of the <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code> module search path</a><ul>108<li><a class="reference internal" href="#virtual-environments">Virtual Environments</a></li>109<li><a class="reference internal" href="#pth-files">_pth files</a></li>110<li><a class="reference internal" href="#embedded-python">Embedded Python</a></li>111</ul>112</li>113</ul>114 115  </div>116  <div>117    <h4>Previous topic</h4>118    <p class="topless"><a href="importlib.metadata.html"119                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.metadata</span></code> – Accessing package metadata</a></p>120  </div>121  <div>122    <h4>Next topic</h4>123    <p class="topless"><a href="language.html"124                          title="next chapter">Python Language Services</a></p>125  </div>126  <script>127    document.addEventListener('DOMContentLoaded', () => {128        const title = document.querySelector('meta[property="og:title"]').content;129        const elements = document.querySelectorAll('.improvepage');130        const pageurl = window.location.href.split('?')[0];131        elements.forEach(element => {132            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));133            url.searchParams.set('pagetitle', title);134            url.searchParams.set('pageurl', pageurl);135            url.searchParams.set('pagesource', "library/sys_path_init.rst");136            element.href = url.toString();137        });138    });139  </script>140  <div role="note" aria-label="source link">141    <h3>This page</h3>142    <ul class="this-page-menu">143      <li><a href="../bugs.html">Report a bug</a></li>144      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>145      <li>146        <a href="https://github.com/python/cpython/blob/main/Doc/library/sys_path_init.rst?plain=1"147            rel="nofollow">Show source148        </a>149      </li>150      151    </ul>152  </div>153        </nav>154    </div>155</div>156 157  158    <div class="related" role="navigation" aria-label="Related">159      <h3>Navigation</h3>160      <ul>161        <li class="right" style="margin-right: 10px">162          <a href="../genindex.html" title="General Index"163             accesskey="I">index</a></li>164        <li class="right" >165          <a href="../py-modindex.html" title="Python Module Index"166             >modules</a> |</li>167        <li class="right" >168          <a href="language.html" title="Python Language Services"169             accesskey="N">next</a> |</li>170        <li class="right" >171          <a href="importlib.metadata.html" title="importlib.metadata – Accessing package metadata"172             accesskey="P">previous</a> |</li>173 174          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>175          <li><a href="https://www.python.org/">Python</a> &#187;</li>176          <li class="switchers">177            <div class="language_switcher_placeholder"></div>178            <div class="version_switcher_placeholder"></div>179          </li>180          <li>181              182          </li>183    <li id="cpython-language-and-version">184      <a href="../index.html">3.15.0a6 Documentation</a> &#187;185    </li>186 187          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>188          <li class="nav-item nav-item-2"><a href="modules.html" accesskey="U">Importing Modules</a> &#187;</li>189        <li class="nav-item nav-item-this"><a href="">The initialization of the <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code> module search path</a></li>190                <li class="right">191                    192 193    <div class="inline-search" role="search">194        <form class="inline-search" action="../search.html" method="get">195          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">196          <input type="submit" value="Go">197        </form>198    </div>199                     |200                </li>201            <li class="right">202<label class="theme-selector-label">203    Theme204    <select class="theme-selector" oninput="activateTheme(this.value)">205        <option value="auto" selected>Auto</option>206        <option value="light">Light</option>207        <option value="dark">Dark</option>208    </select>209</label> |</li>210            211      </ul>212    </div>    213 214    <div class="document">215      <div class="documentwrapper">216        <div class="bodywrapper">217          <div class="body" role="main">218            219  <section id="the-initialization-of-the-sys-path-module-search-path">220<span id="sys-path-init"></span><h1>The initialization of the <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> module search path<a class="headerlink" href="#the-initialization-of-the-sys-path-module-search-path" title="Link to this heading">¶</a></h1>221<p>A module search path is initialized when Python starts. This module search path222may be accessed at <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>.</p>223<p>The first entry in the module search path is the directory that contains the224input script, if there is one. Otherwise, the first entry is the current225directory, which is the case when executing the interactive shell, a <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a>226command, or <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> module.</p>227<p>The <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> environment variable is often used to add directories228to the search path. If this environment variable is found then the contents are229added to the module search path.</p>230<div class="admonition note">231<p class="admonition-title">Note</p>232<p><span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> will affect all installed Python versions/environments.233Be wary of setting this in your shell profile or global environment variables.234The <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module offers more nuanced techniques as mentioned below.</p>235</div>236<p>The next items added are the directories containing standard Python modules as237well as any <a class="reference internal" href="../glossary.html#term-extension-module"><span class="xref std std-term">extension module</span></a>s that these modules depend on. Extension238modules are <code class="docutils literal notranslate"><span class="pre">.pyd</span></code> files on Windows and <code class="docutils literal notranslate"><span class="pre">.so</span></code> files on other platforms. The239directory with the platform-independent Python modules is called <code class="docutils literal notranslate"><span class="pre">prefix</span></code>.240The directory with the extension modules is called <code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code>.</p>241<p>The <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> environment variable may be used to set the <code class="docutils literal notranslate"><span class="pre">prefix</span></code>242and <code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code> locations. Otherwise these directories are found by using243the Python executable as a starting point and then looking for various ‘landmark’244files and directories. Note that any symbolic links are followed so the real245Python executable location is used as the search starting point. The Python246executable location is called <code class="docutils literal notranslate"><span class="pre">home</span></code>.</p>247<p>Once <code class="docutils literal notranslate"><span class="pre">home</span></code> is determined, the <code class="docutils literal notranslate"><span class="pre">prefix</span></code> directory is found by first looking248for <code class="file docutils literal notranslate"><span class="pre">python</span><em><span class="pre">majorversion</span></em><em><span class="pre">minorversion</span></em><span class="pre">.zip</span></code> (<code class="docutils literal notranslate"><span class="pre">python311.zip</span></code>). On Windows249the zip archive is searched for in <code class="docutils literal notranslate"><span class="pre">home</span></code> and on Unix the archive is expected250to be in <code class="file docutils literal notranslate"><span class="pre">lib</span></code>. Note that the expected zip archive location is added to the251module search path even if the archive does not exist. If no archive was found,252Python on Windows will continue the search for <code class="docutils literal notranslate"><span class="pre">prefix</span></code> by looking for <code class="file docutils literal notranslate"><span class="pre">Lib\os.py</span></code>.253Python on Unix will look for <code class="file docutils literal notranslate"><span class="pre">lib/python</span><em><span class="pre">majorversion</span></em><span class="pre">.</span><em><span class="pre">minorversion</span></em><span class="pre">/os.py</span></code>254(<code class="docutils literal notranslate"><span class="pre">lib/python3.11/os.py</span></code>). On Windows <code class="docutils literal notranslate"><span class="pre">prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code> are the same,255however on other platforms <code class="file docutils literal notranslate"><span class="pre">lib/python</span><em><span class="pre">majorversion</span></em><span class="pre">.</span><em><span class="pre">minorversion</span></em><span class="pre">/lib-dynload</span></code>256(<code class="docutils literal notranslate"><span class="pre">lib/python3.11/lib-dynload</span></code>) is searched for and used as an anchor for257<code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code>. On some platforms <code class="file docutils literal notranslate"><span class="pre">lib</span></code> may be <code class="file docutils literal notranslate"><span class="pre">lib64</span></code> or another value,258see <a class="reference internal" href="sys.html#sys.platlibdir" title="sys.platlibdir"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.platlibdir</span></code></a> and <span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPLATLIBDIR"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPLATLIBDIR</span></code></a>.</p>259<p>Once found, <code class="docutils literal notranslate"><span class="pre">prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code> are available at260<a class="reference internal" href="sys.html#sys.base_prefix" title="sys.base_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_prefix</span></code></a> and <a class="reference internal" href="sys.html#sys.base_exec_prefix" title="sys.base_exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_exec_prefix</span></code></a> respectively.</p>261<p>If <span class="target" id="index-4"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> is not set, and a <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> file is found alongside262the main executable, or in its parent directory, <a class="reference internal" href="sys.html#sys.prefix" title="sys.prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.prefix</span></code></a> and263<a class="reference internal" href="sys.html#sys.exec_prefix" title="sys.exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code></a> get set to the directory containing <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code>,264otherwise they are set to the same value as <a class="reference internal" href="sys.html#sys.base_prefix" title="sys.base_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_prefix</span></code></a> and265<a class="reference internal" href="sys.html#sys.base_exec_prefix" title="sys.base_exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_exec_prefix</span></code></a>, respectively.266This is used by <a class="reference internal" href="#sys-path-init-virtual-environments"><span class="std std-ref">Virtual Environments</span></a>.</p>267<p>Finally, the <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module is processed and <code class="file docutils literal notranslate"><span class="pre">site-packages</span></code>268directories are added to the module search path.  The <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUSERBASE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONUSERBASE</span></code></a>269environment variable controls where is searched for user site-packages and the270<span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONNOUSERSITE</span></code></a> environment variable prevents searching for user271site-packages all together.  A common way to customize the search path is to272create <a class="reference internal" href="site.html#module-sitecustomize" title="sitecustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code></a> or <a class="reference internal" href="site.html#module-usercustomize" title="usercustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code></a> modules as described in the273<code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module documentation.</p>274<div class="admonition note">275<p class="admonition-title">Note</p>276<p>The command line options <a class="reference internal" href="../using/cmdline.html#cmdoption-E"><code class="xref std std-option docutils literal notranslate"><span class="pre">-E</span></code></a>, <a class="reference internal" href="../using/cmdline.html#cmdoption-P"><code class="xref std std-option docutils literal notranslate"><span class="pre">-P</span></code></a>, <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a>,277<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal notranslate"><span class="pre">-S</span></code></a> and <a class="reference internal" href="../using/cmdline.html#cmdoption-s"><code class="xref std std-option docutils literal notranslate"><span class="pre">-s</span></code></a> further affect path calculations, see their278documentation for details.</p>279</div>280<div class="versionchanged">281<p><span class="versionmodified changed">Changed in version 3.14: </span><a class="reference internal" href="sys.html#sys.prefix" title="sys.prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.prefix</span></code></a> and <a class="reference internal" href="sys.html#sys.exec_prefix" title="sys.exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code></a> are now set to the282<code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> directory during the path initialization. This was previously283done by <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a>, therefore affected by <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal notranslate"><span class="pre">-S</span></code></a>.</p>284</div>285<section id="virtual-environments">286<span id="sys-path-init-virtual-environments"></span><h2>Virtual Environments<a class="headerlink" href="#virtual-environments" title="Link to this heading">¶</a></h2>287<p>Virtual environments place a <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> file in their prefix, which causes288<a class="reference internal" href="sys.html#sys.prefix" title="sys.prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.prefix</span></code></a> and <a class="reference internal" href="sys.html#sys.exec_prefix" title="sys.exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code></a> to point to them, instead of the289base installation.</p>290<p>The <code class="docutils literal notranslate"><span class="pre">prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">exec_prefix</span></code> values of the base installation are available291at <a class="reference internal" href="sys.html#sys.base_prefix" title="sys.base_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_prefix</span></code></a> and <a class="reference internal" href="sys.html#sys.base_exec_prefix" title="sys.base_exec_prefix"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.base_exec_prefix</span></code></a>.</p>292<p>As well as being used as a marker to identify virtual environments,293<code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> may also be used to configure the <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> initialization.294Please refer to <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code>’s295<a class="reference internal" href="site.html#site-virtual-environments-configuration"><span class="std std-ref">virtual environments documentation</span></a>.</p>296<div class="admonition note">297<p class="admonition-title">Note</p>298<p><span class="target" id="index-7"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> overrides the <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> detection.</p>299</div>300<div class="admonition note">301<p class="admonition-title">Note</p>302<p>There are other ways “virtual environments” could be implemented.303This documentation refers to implementations based on the <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code>304mechanism, such as <a class="reference internal" href="venv.html#module-venv" title="venv: Creation of virtual environments."><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code></a>, that many virtual environment implementations305follow.</p>306</div>307</section>308<section id="pth-files">309<h2>_pth files<a class="headerlink" href="#pth-files" title="Link to this heading">¶</a></h2>310<p>To completely override <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> create a <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file with the same311name as the shared library or executable (<code class="docutils literal notranslate"><span class="pre">python._pth</span></code> or <code class="docutils literal notranslate"><span class="pre">python311._pth</span></code>).312The shared library path is always known on Windows, however it may not be313available on other platforms. In the <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file specify one line for each path314to add to <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code>. The file based on the shared library name overrides315the one based on the executable, which allows paths to be restricted for any316program loading the runtime if desired.</p>317<p>When the file exists, all registry and environment variables are ignored,318isolated mode is enabled, and <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> is not imported unless one line in the319file specifies <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">site</span></code>. Blank paths and lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> are320ignored. Each path may be absolute or relative to the location of the file.321Import statements other than to <code class="docutils literal notranslate"><span class="pre">site</span></code> are not permitted, and arbitrary code322cannot be specified.</p>323<p>Note that <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files (without leading underscore) will be processed normally324by the <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module when <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">site</span></code> has been specified.</p>325</section>326<section id="embedded-python">327<h2>Embedded Python<a class="headerlink" href="#embedded-python" title="Link to this heading">¶</a></h2>328<p>If Python is embedded within another application <a class="reference internal" href="../c-api/interp-lifecycle.html#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a> and329the <a class="reference internal" href="../c-api/init_config.html#c.PyConfig" title="PyConfig"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyConfig</span></code></a> structure can be used to initialize Python. The path specific330details are described at <a class="reference internal" href="../c-api/init_config.html#init-path-config"><span class="std std-ref">Python Path Configuration</span></a>.</p>331<div class="admonition seealso">332<p class="admonition-title">See also</p>333<ul class="simple">334<li><p><a class="reference internal" href="../using/windows.html#windows-finding-modules"><span class="std std-ref">Finding modules</span></a> for detailed Windows notes.</p></li>335<li><p><a class="reference internal" href="../using/unix.html#using-on-unix"><span class="std std-ref">Using Python on Unix platforms</span></a> for Unix details.</p></li>336</ul>337</div>338</section>339</section>340 341 342            <div class="clearer"></div>343          </div>344        </div>345      </div>346      <div class="sphinxsidebar" role="navigation" aria-label="Main">347        <div class="sphinxsidebarwrapper">348  <div>349    <h3><a href="../contents.html">Table of Contents</a></h3>350    <ul>351<li><a class="reference internal" href="#">The initialization of the <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code> module search path</a><ul>352<li><a class="reference internal" href="#virtual-environments">Virtual Environments</a></li>353<li><a class="reference internal" href="#pth-files">_pth files</a></li>354<li><a class="reference internal" href="#embedded-python">Embedded Python</a></li>355</ul>356</li>357</ul>358 359  </div>360  <div>361    <h4>Previous topic</h4>362    <p class="topless"><a href="importlib.metadata.html"363                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.metadata</span></code> – Accessing package metadata</a></p>364  </div>365  <div>366    <h4>Next topic</h4>367    <p class="topless"><a href="language.html"368                          title="next chapter">Python Language Services</a></p>369  </div>370  <script>371    document.addEventListener('DOMContentLoaded', () => {372        const title = document.querySelector('meta[property="og:title"]').content;373        const elements = document.querySelectorAll('.improvepage');374        const pageurl = window.location.href.split('?')[0];375        elements.forEach(element => {376            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));377            url.searchParams.set('pagetitle', title);378            url.searchParams.set('pageurl', pageurl);379            url.searchParams.set('pagesource', "library/sys_path_init.rst");380            element.href = url.toString();381        });382    });383  </script>384  <div role="note" aria-label="source link">385    <h3>This page</h3>386    <ul class="this-page-menu">387      <li><a href="../bugs.html">Report a bug</a></li>388      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>389      <li>390        <a href="https://github.com/python/cpython/blob/main/Doc/library/sys_path_init.rst?plain=1"391            rel="nofollow">Show source392        </a>393      </li>394      395    </ul>396  </div>397        </div>398<div id="sidebarbutton" title="Collapse sidebar">399<span>«</span>400</div>401 402      </div>403      <div class="clearer"></div>404    </div>  405    <div class="related" role="navigation" aria-label="Related">406      <h3>Navigation</h3>407      <ul>408        <li class="right" style="margin-right: 10px">409          <a href="../genindex.html" title="General Index"410             >index</a></li>411        <li class="right" >412          <a href="../py-modindex.html" title="Python Module Index"413             >modules</a> |</li>414        <li class="right" >415          <a href="language.html" title="Python Language Services"416             >next</a> |</li>417        <li class="right" >418          <a href="importlib.metadata.html" title="importlib.metadata – Accessing package metadata"419             >previous</a> |</li>420 421          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>422          <li><a href="https://www.python.org/">Python</a> &#187;</li>423          <li class="switchers">424            <div class="language_switcher_placeholder"></div>425            <div class="version_switcher_placeholder"></div>426          </li>427          <li>428              429          </li>430    <li id="cpython-language-and-version">431      <a href="../index.html">3.15.0a6 Documentation</a> &#187;432    </li>433 434          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>435          <li class="nav-item nav-item-2"><a href="modules.html" >Importing Modules</a> &#187;</li>436        <li class="nav-item nav-item-this"><a href="">The initialization of the <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code> module search path</a></li>437                <li class="right">438                    439 440    <div class="inline-search" role="search">441        <form class="inline-search" action="../search.html" method="get">442          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">443          <input type="submit" value="Go">444        </form>445    </div>446                     |447                </li>448            <li class="right">449<label class="theme-selector-label">450    Theme451    <select class="theme-selector" oninput="activateTheme(this.value)">452        <option value="auto" selected>Auto</option>453        <option value="light">Light</option>454        <option value="dark">Dark</option>455    </select>456</label> |</li>457            458      </ul>459    </div>  460    <div class="footer">461    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.462    <br>463    This page is licensed under the Python Software Foundation License Version 2.464    <br>465    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.466    <br>467    468      See <a href="/license.html">History and License</a> for more information.<br>469    470    471    <br>472 473    The Python Software Foundation is a non-profit corporation.474<a href="https://www.python.org/psf/donations/">Please donate.</a>475<br>476    <br>477      Last updated on Mar 10, 2026 (08:58 UTC).478    479      <a href="/bugs.html">Found a bug</a>?480    481    <br>482 483    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.484    </div>485 486  </body>487</html>