CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 250 – Using site-packages on Windows | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0250/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 250 – Using site-packages on Windows | peps.python.org'> <meta property="og:description" content="The standard Python distribution includes a directory Lib/site-packages, which is used on Unix platforms to hold locally installed modules and packages. The site.py module distributed with Python includes support for locating other modules in the site-..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0250/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="The standard Python distribution includes a directory Lib/site-packages, which is used on Unix platforms to hold locally installed modules and packages. The site.py module distributed with Python includes support for locating other modules in the site-..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 250</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 250 – Using site-packages on Windows</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Paul Moore <p.f.moore at gmail.com></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">30-Mar-2001</dd> <dt class="field-odd">Python-Version<span class="colon">:</span></dt> <dd class="field-odd">2.2</dd> <dt class="field-even">Post-History<span class="colon">:</span></dt> <dd class="field-even">30-Mar-2001</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#notes">Notes</a></li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>The standard Python distribution includes a directory <code class="docutils literal notranslate"><span class="pre">Lib/site-packages</span></code>, which is used on Unix platforms to hold locally installed modules and packages. The <code class="docutils literal notranslate"><span class="pre">site.py</span></code> module distributed with Python includes support for locating other modules in the site-packages directory.</p> <p>This PEP proposes that the site-packages directory should be used on the Windows platform in a similar manner.</p> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <p>On Windows platforms, the default setting for <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> does not include a directory suitable for users to install locally developed modules. The “expected” location appears to be the directory containing the Python executable itself. This is also the location where distutils (and distutils-generated installers) installs packages. Including locally developed code in the same directory as installed executables is not good practice.</p> <p>Clearly, users can manipulate <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, either in a locally modified <code class="docutils literal notranslate"><span class="pre">site.py</span></code>, or in a suitable <code class="docutils literal notranslate"><span class="pre">sitecustomize.py</span></code>, or even via <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files. However, there should be a standard location for such files, rather than relying on every individual site having to set their own policy.</p> <p>In addition, with distutils becoming more prevalent as a means of distributing modules, the need for a standard install location for distributed modules will become more common. It would be better to define such a standard now, rather than later when more distutils-based packages exist which will need rebuilding.</p> <p>It is relevant to note that prior to Python 2.1, the site-packages directory was not included in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> for Macintosh platforms. This has been changed in 2.1, and Macintosh includes <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> now, leaving Windows as the only major platform with no site-specific modules directory.</p> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <p>The implementation of this feature is fairly trivial. All that would be required is a change to <code class="docutils literal notranslate"><span class="pre">site.py</span></code>, to change the section setting sitedirs. The Python 2.1 version has:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">sep</span> <span class="o">==</span> <span class="s1">'/'</span><span class="p">:</span> <span class="n">sitedirs</span> <span class="o">=</span> <span class="p">[</span><span class="n">makepath</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="s2">"lib"</span><span class="p">,</span> <span class="s2">"python"</span> <span class="o">+</span> <span class="n">sys</span><span class="o">.</span><span class="n">version</span><span class="p">[:</span><span class="mi">3</span><span class="p">],</span> <span class="s2">"site-packages"</span><span class="p">),</span> <span class="n">makepath</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="s2">"lib"</span><span class="p">,</span> <span class="s2">"site-python"</span><span class="p">)]</span> <span class="k">elif</span> <span class="n">os</span><span class="o">.</span><span class="n">sep</span> <span class="o">==</span> <span class="s1">':'</span><span class="p">:</span> <span class="n">sitedirs</span> <span class="o">=</span> <span class="p">[</span><span class="n">makepath</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="s2">"lib"</span><span class="p">,</span> <span class="s2">"site-packages"</span><span class="p">)]</span> <span class="k">else</span><span class="p">:</span> <span class="n">sitedirs</span> <span class="o">=</span> <span class="p">[</span><span class="n">prefix</span><span class="p">]</span> </pre></div> </div> <p>A suitable change would be to simply replace the last 4 lines with:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">else</span><span class="p">:</span> <span class="n">sitedirs</span> <span class="o">==</span> <span class="p">[</span><span class="n">prefix</span><span class="p">,</span> <span class="n">makepath</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="s2">"lib"</span><span class="p">,</span> <span class="s2">"site-packages"</span><span class="p">)]</span> </pre></div> </div> <p>Changes would also be required to distutils, to reflect this change in policy. A patch is available on Sourceforge, patch ID 445744, which implements this change. Note that the patch checks the Python version and only invokes the new behaviour for Python versions from 2.2 onwards. This is to ensure that distutils remains compatible with earlier versions of Python.</p> <p>Finally, the executable code which implements the Windows installer used by the <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> command will need changing to use the new location. A separate patch is available for this, currently maintained by Thomas Heller.</p> </section> <section id="notes"> <h2><a class="toc-backref" href="#notes" role="doc-backlink">Notes</a></h2> <ul class="simple"> <li>This change does not preclude packages using the current location – the change only adds a directory to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, it does not remove anything.</li> <li>Both the current location (<code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code>) and the new directory (site-packages) are included in sitedirs, so that <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files will be recognised in either location.</li> <li>This proposal adds a single additional site-packages directory to sitedirs. On Unix platforms, two directories are added, one for version-independent files (Python code) and one for version-dependent code (C extensions). This is necessary on Unix, as the sitedirs include a common (across Python versions) package location, in <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code> by default. As there is no such common location available on Windows, there is also no need for having two separate package directories.</li> <li>If users want to keep DLLs in a single location on Windows, rather than keeping them in the package directory, the DLLs subdirectory of the Python install directory is already available for that purpose. Adding an extra directory solely for DLLs should not be necessary.</li> </ul> </section> <section id="open-issues"> <h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2> <ul class="simple"> <li>Comments from Unix users indicate that there may be issues with the current setup on the Unix platform. Rather than become involved in cross-platform issues, this PEP specifically limits itself to the Windows platform, leaving changes for other platforms to be covered in other PEPs.</li> <li>There could be issues with applications which embed Python. To the author’s knowledge, there should be no problem as a result of this change. There have been no comments (supportive or otherwise) from users who embed Python.</li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0250.rst">https://github.com/python/peps/blob/main/peps/pep-0250.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0250.rst">2025-02-01 08:55:40 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#notes">Notes</a></li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0250.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>