Files
FootPrint/Python/pythoncore-3.15-64/Doc/html/library/site.html
T

839 lines
75 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="site — Site-specific configuration hook" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/site.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/site.py This module is automatically imported during initialization. The automatic import can be suppressed using the interpreter’s-S option. Importing this module normally appends..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/site.py This module is automatically imported during initialization. The automatic import can be suppressed using the interpreter’s-S option. Importing this module normally appends..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>site — Site-specific configuration hook &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Custom Python Interpreters" href="custominterp.html" />
<link rel="prev" title="annotationlib — Functionality for introspecting annotations" href="annotationlib.html" />
<link rel="canonical" href="https://docs.python.org/3/library/site.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<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>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> — Site-specific configuration hook</a><ul>
<li><a class="reference internal" href="#path-extensions-pth-files">Path extensions (<code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files)</a></li>
<li><a class="reference internal" href="#startup-entry-points-start-files">Startup entry points (<code class="file docutils literal notranslate"><span class="pre">.start</span></code> files)</a></li>
<li><a class="reference internal" href="#startup-file-examples">Startup file examples</a></li>
<li><a class="reference internal" href="#migrating-from-import-lines-in-pth-files-to-start-files">Migrating from <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files to <code class="docutils literal notranslate"><span class="pre">.start</span></code> files</a></li>
<li><a class="reference internal" href="#module-sitecustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code></a></li>
<li><a class="reference internal" href="#module-usercustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code></a></li>
<li><a class="reference internal" href="#readline-configuration">Readline configuration</a></li>
<li><a class="reference internal" href="#module-contents">Module contents</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="annotationlib.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">annotationlib</span></code> — Functionality for introspecting annotations</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="custominterp.html"
title="next chapter">Custom Python Interpreters</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/site.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/site.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="custominterp.html" title="Custom Python Interpreters"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="annotationlib.html" title="annotationlib — Functionality for introspecting annotations"
accesskey="P">previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python Runtime Services</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> — Site-specific configuration hook</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-site">
<span id="site-site-specific-configuration-hook"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> — Site-specific configuration hook<a class="headerlink" href="#module-site" title="Link to this heading"></a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/site.py">Lib/site.py</a></p>
<hr class="docutils" />
<p><strong>This module is automatically imported during initialization.</strong> The automatic
import can be suppressed using the interpreter’s <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> option.</p>
<p id="index-0">Importing this module normally appends site-specific paths to the module search path
and adds <a class="reference internal" href="../builtins/constants.html#site-consts"><span class="std std-ref">callables</span></a>, including <a class="reference internal" href="../builtins/functions.html#help" title="help"><code class="xref py py-func docutils literal notranslate"><span class="pre">help()</span></code></a> to the built-in
namespace. However, Python startup option <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> blocks this, and this module
can be safely imported with no automatic modifications to the module search path
or additions to the builtins. To explicitly trigger the usual site-specific
additions, call the <a class="reference internal" href="#site.main" title="site.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a> function.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.3: </span>Importing the module used to trigger paths manipulation even when using
<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>
</div>
<p id="index-1">It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code>; empty heads
are skipped. For the tail part, it uses the empty string and then
<code class="file docutils literal notranslate"><span class="pre">lib/site-packages</span></code> (on Windows) or
<code class="file docutils literal notranslate"><span class="pre">lib/python</span><em><span class="pre">X.Y[t]</span></em><span class="pre">/site-packages</span></code> (on Unix and macOS). (The
optional suffix “t” indicates the <a class="reference internal" href="../glossary.html#term-free-threaded-build"><span class="xref std std-term">free-threaded build</span></a>, and is
appended if <code class="docutils literal notranslate"><span class="pre">&quot;t&quot;</span></code> is present in the <a class="reference internal" href="sys.html#sys.abiflags" title="sys.abiflags"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.abiflags</span></code></a> constant.)
For each
of the distinct head-tail combinations, it sees if it refers to an existing
directory, and if so, adds it to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> and also inspects the newly
added path for configuration files.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.5: </span>Support for the “site-python” directory has been removed.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.13: </span>On Unix, <a class="reference internal" href="../glossary.html#term-free-threading"><span class="xref std std-term">Free threading</span></a> Python installations are
identified by the “t” suffix in the version-specific directory name, such as
<code class="file docutils literal notranslate"><span class="pre">lib/python3.13t/</span></code>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> is no longer responsible for updating <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> on <a class="reference internal" href="sys_path_init.html#sys-path-init-virtual-environments"><span class="std std-ref">Virtual Environments</span></a>. This is
now done during the <a class="reference internal" href="sys_path_init.html#sys-path-init"><span class="std std-ref">path initialization</span></a>. As a result,
under <a class="reference internal" href="sys_path_init.html#sys-path-init-virtual-environments"><span class="std std-ref">Virtual Environments</span></a>, <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.prefix</span></code> and
<code class="xref py py-data docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code> no longer depend on the <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> initialization,
and are therefore unaffected 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>
</div>
<p id="site-virtual-environments-configuration">When running under a <a class="reference internal" href="sys_path_init.html#sys-path-init-virtual-environments"><span class="std std-ref">virtual environment</span></a>,
the <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> file in <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> is checked for site-specific
configurations. If the <code class="docutils literal notranslate"><span class="pre">include-system-site-packages</span></code> key exists and is set to
<code class="docutils literal notranslate"><span class="pre">true</span></code> (case-insensitive), the system-level prefixes will be searched for
site-packages, otherwise they won’t. If the system-level prefixes are not searched then
the user site prefixes are also implicitly not searched for site-packages.</p>
<p id="index-2">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module recognizes two startup configuration files of the form
<code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> for path configurations, and <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> for
pre-first-line code execution. Both files can exist in one of the four
directories mentioned above. Within each directory, these files are sorted
alphabetically by filename, then parsed in sorted order.</p>
<section id="path-extensions-pth-files">
<span id="site-pth-files"></span><h2>Path extensions (<code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files)<a class="headerlink" href="#path-extensions-pth-files" title="Link to this heading"></a></h2>
<p><code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> contains additional items (one per line) to be appended to
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>. Items that name non-existing directories are never added to
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, and no check is made that the item refers to a directory rather
than a file. No item is added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> more than once. Blank lines
and lines beginning with <code class="docutils literal notranslate"><span class="pre">#</span></code> are skipped.</p>
<p>For backward compatibility, lines starting with <code class="docutils literal notranslate"><span class="pre">import</span></code> (followed by space
or tab) are executed with <a class="reference internal" href="../builtins/functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.13: </span>The <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files are now decoded by UTF-8 at first and then by the
<a class="reference internal" href="../glossary.html#term-locale-encoding"><span class="xref std std-term">locale encoding</span></a> if it fails.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span><code class="file docutils literal notranslate"><span class="pre">.pth</span></code> file lines starting with <code class="docutils literal notranslate"><span class="pre">import</span></code> are deprecated. During
the deprecation period, such lines are still executed (except in the case
below), but a diagnostic message is emitted only when the <a class="reference internal" href="../using/cmdline.html#cmdoption-v"><code class="xref std std-option docutils literal notranslate"><span class="pre">-v</span></code></a> flag
is given.</p>
<p><code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> are silently ignored when a
<a class="reference internal" href="#site-start-files"><span class="std std-ref">matching</span></a> <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> file exists.</p>
<p>Errors on individual lines no longer abort processing of the rest of the
file. Each error is reported and the remaining lines continue to be
processed.</p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified deprecated">Deprecated since version 3.15, will be removed in version 3.20: </span>Decoding <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> files in any encoding other than <code class="docutils literal notranslate"><span class="pre">utf-8-sig</span></code>
is deprecated in Python 3.15, and support for decoding from the locale
encoding will be removed in Python 3.20.</p>
<p><code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> files are deprecated and will be
silently ignored in Python 3.18 and 3.19. In Python 3.20 a warning will be
produced for <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> files.</p>
</div>
</section>
<section id="startup-entry-points-start-files">
<span id="site-start-files"></span><h2>Startup entry points (<code class="file docutils literal notranslate"><span class="pre">.start</span></code> files)<a class="headerlink" href="#startup-entry-points-start-files" title="Link to this heading"></a></h2>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
<p>A startup entry point file is a file whose name has the form
<code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> and exists in one of the site-packages directories
described above. Each file specifies entry points to be called during
interpreter startup, using the <code class="docutils literal notranslate"><span class="pre">pkg.mod:callable</span></code> syntax understood by
<a class="reference internal" href="pkgutil.html#pkgutil.resolve_name" title="pkgutil.resolve_name"><code class="xref py py-func docutils literal notranslate"><span class="pre">pkgutil.resolve_name()</span></code></a>.</p>
<p>Each non-blank line that does not begin with <code class="docutils literal notranslate"><span class="pre">#</span></code> must contain an entry
point reference in the form <code class="docutils literal notranslate"><span class="pre">pkg.mod:callable</span></code>. The colon and callable
portion are mandatory. Each callable is invoked with no arguments, and
any return value is discarded.</p>
<p><code class="file docutils literal notranslate"><span class="pre">.start</span></code> files are processed after all <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> path extensions
have been applied to <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>, ensuring that paths are available
before any startup code runs.</p>
<p>Unlike <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> extensions from <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files, duplicate entry
points are <strong>not</strong> de-duplicated — if an entry point appears more than once,
it will be called more than once.</p>
<p>If an exception occurs during resolution or invocation of an entry point,
a traceback is printed to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> and processing continues with
the remaining entry points.</p>
<p><code class="file docutils literal notranslate"><span class="pre">.start</span></code> files must be encoded in UTF-8.</p>
<p><span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-0829/"><strong>PEP 829</strong></a> defined the original specification for these features.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If a <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> file exists alongside a <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> file
with the same base name, any <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in the <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> file are
ignored in favor of the entry points in the <code class="file docutils literal notranslate"><span class="pre">.start</span></code> file.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Executable lines (<code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> files and
<code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> file entry points) are always run at Python startup
(unless <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> is given to disable the <code class="docutils literal notranslate"><span class="pre">site.py</span></code> module entirely),
regardless of whether a particular module is actually going to be used.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> files invoke <a class="reference internal" href="pkgutil.html#pkgutil.resolve_name" title="pkgutil.resolve_name"><code class="xref py py-func docutils literal notranslate"><span class="pre">pkgutil.resolve_name()</span></code></a> with
<code class="docutils literal notranslate"><span class="pre">strict=True</span></code>, which requires the full <code class="docutils literal notranslate"><span class="pre">pkg.mod:callable</span></code> form.</p>
</div>
</section>
<section id="startup-file-examples">
<span id="index-4"></span><h2>Startup file examples<a class="headerlink" href="#startup-file-examples" title="Link to this heading"></a></h2>
<p>For example, suppose <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code> are set to
<code class="file docutils literal notranslate"><span class="pre">/usr/local</span></code>. The Python X.Y library is then installed in
<code class="file docutils literal notranslate"><span class="pre">/usr/local/lib/python</span><em><span class="pre">X.Y</span></em></code>. Suppose this has
a subdirectory <code class="file docutils literal notranslate"><span class="pre">/usr/local/lib/python</span><em><span class="pre">X.Y</span></em><span class="pre">/site-packages</span></code> with three
sub-subdirectories, <code class="file docutils literal notranslate"><span class="pre">foo</span></code>, <code class="file docutils literal notranslate"><span class="pre">bar</span></code> and <code class="file docutils literal notranslate"><span class="pre">spam</span></code>, and two path
configuration files, <code class="file docutils literal notranslate"><span class="pre">foo.pth</span></code> and <code class="file docutils literal notranslate"><span class="pre">bar.pth</span></code>. Assume
<code class="file docutils literal notranslate"><span class="pre">foo.pth</span></code> contains the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># foo package configuration
foo
bar
bletch
</pre></div>
</div>
<p>and <code class="file docutils literal notranslate"><span class="pre">bar.pth</span></code> contains:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># bar package configuration
bar
</pre></div>
</div>
<p>Then the following version-specific directories are added to
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, in this order:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
</pre></div>
</div>
<p>Note that <code class="file docutils literal notranslate"><span class="pre">bletch</span></code> is omitted because it doesn’t exist; the <code class="file docutils literal notranslate"><span class="pre">bar</span></code>
directory precedes the <code class="file docutils literal notranslate"><span class="pre">foo</span></code> directory because <code class="file docutils literal notranslate"><span class="pre">bar.pth</span></code> comes
alphabetically before <code class="file docutils literal notranslate"><span class="pre">foo.pth</span></code>; and <code class="file docutils literal notranslate"><span class="pre">spam</span></code> is omitted because it is
not mentioned in either path configuration file.</p>
<p>Let’s say that there is also a <code class="file docutils literal notranslate"><span class="pre">foo.start</span></code> file containing the
following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># foo package startup code
foo.submod:initialize
</pre></div>
</div>
<p>Now, after <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> has been extended as above, and before Python turns
control over to user code, the <code class="docutils literal notranslate"><span class="pre">foo.submod</span></code> module is imported and the
<code class="docutils literal notranslate"><span class="pre">initialize()</span></code> function from that module is called.</p>
</section>
<section id="migrating-from-import-lines-in-pth-files-to-start-files">
<span id="site-migration-guide"></span><h2>Migrating from <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files to <code class="docutils literal notranslate"><span class="pre">.start</span></code> files<a class="headerlink" href="#migrating-from-import-lines-in-pth-files-to-start-files" title="Link to this heading"></a></h2>
<p>If your package currently ships a <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> file, you can keep all
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> extension lines unchanged. Only <code class="docutils literal notranslate"><span class="pre">import</span></code> lines need to be
migrated.</p>
<p>To migrate, create a callable (taking zero arguments) within an importable
module in your package. Reference it as a <code class="docutils literal notranslate"><span class="pre">pkg.mod:callable</span></code> entry point
in a matching <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> file. Move everything on your <code class="docutils literal notranslate"><span class="pre">import</span></code>
line after the first semi-colon into the <code class="docutils literal notranslate"><span class="pre">callable()</span></code> function.</p>
<p>If your package must straddle older Pythons that do not support <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0829/"><strong>PEP 829</strong></a>
and newer Pythons that do, change the <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in your
<code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.pth</span></code> to use the following form:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pkg.mod</span><span class="p">;</span> <span class="n">pkg</span><span class="o">.</span><span class="n">mod</span><span class="o">.</span><span class="n">callable</span><span class="p">()</span>
</pre></div>
</div>
<p>Older Pythons will execute these <code class="docutils literal notranslate"><span class="pre">import</span></code> lines, while newer Pythons will
ignore them in favor of the <code class="file docutils literal notranslate"><em><span class="pre">name</span></em><span class="pre">.start</span></code> file. After the straddling
period, remove all <code class="docutils literal notranslate"><span class="pre">import</span></code> lines from your <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files.</p>
</section>
<section id="module-sitecustomize">
<span id="sitecustomize"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code><a class="headerlink" href="#module-sitecustomize" title="Link to this heading"></a></h2>
<p>After these path manipulations, an attempt is made to import a module named
<code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code>, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an <a class="reference internal" href="../builtins/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> or its subclass
exception, and the exception’s <a class="reference internal" href="../builtins/exceptions.html#ImportError.name" title="ImportError.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a>
attribute equals <code class="docutils literal notranslate"><span class="pre">'sitecustomize'</span></code>,
it is silently ignored. If Python is started without output streams available, as
with <code class="file docutils literal notranslate"><span class="pre">pythonw.exe</span></code> on Windows (which is used by default to start IDLE),
attempted output from <code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code> is ignored. Any other exception
causes a silent and perhaps mysterious failure of the process.</p>
</section>
<section id="module-usercustomize">
<span id="usercustomize"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code><a class="headerlink" href="#module-usercustomize" title="Link to this heading"></a></h2>
<p>After this, an attempt is made to import a module named <code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code>,
which can perform arbitrary user-specific customizations, if
<a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">ENABLE_USER_SITE</span></code></a> is true. This file is intended to be created in the
user site-packages directory (see below), which is part of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> unless
disabled 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>. If this import fails with an <a class="reference internal" href="../builtins/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> or
its subclass exception, and the exception’s <a class="reference internal" href="../builtins/exceptions.html#ImportError.name" title="ImportError.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a>
attribute equals <code class="docutils literal notranslate"><span class="pre">'usercustomize'</span></code>, it is silently ignored.</p>
<p>Note that for some non-Unix systems, <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code> are
empty, and the path manipulations are skipped; however the import of
<a class="reference internal" href="#module-sitecustomize" title="sitecustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code></a> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code> is still attempted.</p>
</section>
<section id="readline-configuration">
<span id="rlcompleter-config"></span><h2>Readline configuration<a class="headerlink" href="#readline-configuration" title="Link to this heading"></a></h2>
<p>On systems that support <a class="reference internal" href="readline.html#module-readline" title="readline: GNU readline support for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">readline</span></code></a>, this module will also import and
configure the <a class="reference internal" href="rlcompleter.html#module-rlcompleter" title="rlcompleter: Python identifier completion, suitable for the GNU readline library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">rlcompleter</span></code></a> module, if Python is started in
<a class="reference internal" href="../tutorial/interpreter.html#tut-interactive"><span class="std std-ref">interactive mode</span></a> and without the <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> option.
The default behavior is to enable tab completion and to use
<code class="file docutils literal notranslate"><span class="pre">~/.python_history</span></code> as the history save file. To disable it, delete (or
override) the <a class="reference internal" href="sys.html#sys.__interactivehook__" title="sys.__interactivehook__"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.__interactivehook__</span></code></a> attribute in your
<a class="reference internal" href="#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="#module-usercustomize" title="usercustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code></a> module or your
<span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONSTARTUP"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONSTARTUP</span></code></a> file.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span>Activation of rlcompleter and history was made automatic.</p>
</div>
</section>
<section id="module-contents">
<h2>Module contents<a class="headerlink" href="#module-contents" title="Link to this heading"></a></h2>
<dl class="py data">
<dt class="sig sig-object py" id="site.PREFIXES">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">PREFIXES</span></span><a class="headerlink" href="#site.PREFIXES" title="Link to this definition"></a></dt>
<dd><p>A list of prefixes for site-packages directories.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="site.ENABLE_USER_SITE">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">ENABLE_USER_SITE</span></span><a class="headerlink" href="#site.ENABLE_USER_SITE" title="Link to this definition"></a></dt>
<dd><p>Flag showing the status of the user site-packages directory. <code class="docutils literal notranslate"><span class="pre">True</span></code> means
that it is enabled and was added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>. <code class="docutils literal notranslate"><span class="pre">False</span></code> means that it
was disabled by user request (with <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> or
<span class="target" id="index-7"></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>). <code class="docutils literal notranslate"><span class="pre">None</span></code> means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="site.USER_SITE">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">USER_SITE</span></span><a class="headerlink" href="#site.USER_SITE" title="Link to this definition"></a></dt>
<dd><p>Path to the user site-packages for the running Python. Can be <code class="docutils literal notranslate"><span class="pre">None</span></code> if
<a class="reference internal" href="#site.getusersitepackages" title="site.getusersitepackages"><code class="xref py py-func docutils literal notranslate"><span class="pre">getusersitepackages()</span></code></a> hasn’t been called yet. Default value is
<code class="file docutils literal notranslate"><span class="pre">~/.local/lib/python</span><em><span class="pre">X.Y</span></em><span class="pre">[t]/site-packages</span></code> for UNIX and non-framework
macOS builds, <code class="file docutils literal notranslate"><span class="pre">~/Library/Python/</span><em><span class="pre">X.Y</span></em><span class="pre">/lib/python/site-packages</span></code> for macOS
framework builds, and <code class="file docutils literal notranslate"><em><span class="pre">%APPDATA%</span></em><span class="pre">\Python\Python</span><em><span class="pre">XY</span></em><span class="pre">\site-packages</span></code>
on Windows. The optional “t” indicates the free-threaded build. This
directory is a site directory, which means that <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files in it
will be processed.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="site.USER_BASE">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">USER_BASE</span></span><a class="headerlink" href="#site.USER_BASE" title="Link to this definition"></a></dt>
<dd><p>Path to the base directory for the user site-packages. Can be <code class="docutils literal notranslate"><span class="pre">None</span></code> if
<a class="reference internal" href="#site.getuserbase" title="site.getuserbase"><code class="xref py py-func docutils literal notranslate"><span class="pre">getuserbase()</span></code></a> hasn’t been called yet. Default value is
<code class="file docutils literal notranslate"><span class="pre">~/.local</span></code> for UNIX and macOS non-framework builds,
<code class="file docutils literal notranslate"><span class="pre">~/Library/Python/</span><em><span class="pre">X.Y</span></em></code> for macOS framework builds, and
<code class="file docutils literal notranslate"><em><span class="pre">%APPDATA%</span></em><span class="pre">\Python</span></code> for Windows. This value is used to
compute the installation directories for scripts, data files, Python modules,
etc. for the <a class="reference internal" href="sysconfig.html#sysconfig-user-scheme"><span class="std std-ref">user installation scheme</span></a>.
See also <span class="target" id="index-8"></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>.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.main">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#site.main" title="Link to this definition"></a></dt>
<dd><p>Adds all the standard site-specific directories to the module search
path. This function is called automatically when this module is imported,
unless the Python interpreter was started with the <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> flag.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.3: </span>This function used to be called unconditionally.</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.makepath">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">makepath</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">paths</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.makepath" title="Link to this definition"></a></dt>
<dd><p>Join <em>paths</em> with <a class="reference internal" href="os.path.html#os.path.join" title="os.path.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.join()</span></code></a>, attempt to make the result
absolute with <a class="reference internal" href="os.path.html#os.path.abspath" title="os.path.abspath"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.abspath()</span></code></a>, and return a 2-tuple containing
the absolute path and its case-normalized form as produced by
<a class="reference internal" href="os.path.html#os.path.normcase" title="os.path.normcase"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.normcase()</span></code></a>. If <code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.abspath()</span></code> raises
<a class="reference internal" href="../builtins/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>, the joined path is used unchanged for the
case-normalization step.</p>
<p>The second element of the returned tuple is the form used throughout the
<code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module to compare paths on case-insensitive file systems, and
is what populates the <code class="docutils literal notranslate"><span class="pre">known_paths</span></code> sets that prevent duplicate
<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> entries in various APIs within this module.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="site.StartupState">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">StartupState</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">known_paths</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.StartupState" title="Link to this definition"></a></dt>
<dd><p>Instances of this class accumulate interpreter startup configuration data
from one or more site directories. They are the preferred interface for
batching the processing of <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> and <code class="file docutils literal notranslate"><span class="pre">.start</span></code> files across
multiple site directories, so that every <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> extension is
visible before any startup code runs.</p>
<p>The optional <em>known_paths</em> argument is a set of case-normalized paths
(which can be produced by <a class="reference internal" href="#site.makepath" title="site.makepath"><code class="xref py py-func docutils literal notranslate"><span class="pre">makepath()</span></code></a>) used to prevent duplicate
<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> entries. When <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), the set is built
from the current <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code>. <a class="reference internal" href="#site.main" title="site.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a> implicitly uses an
instance of this class.</p>
<p>Typical use:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">state</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">StartupState</span><span class="p">()</span>
<span class="k">for</span> <span class="n">sitedir</span> <span class="ow">in</span> <span class="n">site_dirs</span><span class="p">:</span>
<span class="n">state</span><span class="o">.</span><span class="n">addsitedir</span><span class="p">(</span><span class="n">sitedir</span><span class="p">)</span>
<span class="n">state</span><span class="o">.</span><span class="n">process</span><span class="p">()</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="site.StartupState.addsitedir">
<span class="sig-name descname"><span class="pre">addsitedir</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sitedir</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.StartupState.addsitedir" title="Link to this definition"></a></dt>
<dd><p>Read the <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> and <code class="file docutils literal notranslate"><span class="pre">.start</span></code> files in <em>sitedir</em> and
record their <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> extensions, deprecated <code class="file docutils literal notranslate"><span class="pre">.pth</span></code>
<code class="docutils literal notranslate"><span class="pre">import</span></code> lines, and <code class="file docutils literal notranslate"><span class="pre">.start</span></code> entry points on this state.
The recorded data is not applied until <a class="reference internal" href="#site.StartupState.process" title="site.StartupState.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">process()</span></code></a> is called.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="site.StartupState.addusersitepackages">
<span class="sig-name descname"><span class="pre">addusersitepackages</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#site.StartupState.addusersitepackages" title="Link to this definition"></a></dt>
<dd><p>Add the per-user site-packages directory, if enabled and if it exists.
The directory’s startup data is accumulated for later processing by
<a class="reference internal" href="#site.StartupState.process" title="site.StartupState.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">process()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="site.StartupState.addsitepackages">
<span class="sig-name descname"><span class="pre">addsitepackages</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefixes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.StartupState.addsitepackages" title="Link to this definition"></a></dt>
<dd><p>Add global site-packages directories, computed from <em>prefixes</em> or from
the global <a class="reference internal" href="#site.PREFIXES" title="site.PREFIXES"><code class="xref py py-data docutils literal notranslate"><span class="pre">PREFIXES</span></code></a> when <em>prefixes</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>. Each
directory’s startup data is accumulated for later processing by
<a class="reference internal" href="#site.StartupState.process" title="site.StartupState.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">process()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="site.StartupState.process">
<span class="sig-name descname"><span class="pre">process</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#site.StartupState.process" title="Link to this definition"></a></dt>
<dd><p>Apply the accumulated state by first adding the path extensions to
<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>, then executing the <code class="file docutils literal notranslate"><span class="pre">.start</span></code> file entry points
and <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> file <code class="docutils literal notranslate"><span class="pre">import</span></code> lines (<a class="reference internal" href="#site-pth-files"><span class="std std-ref">deprecated</span></a>).</p>
<p>This method is not idempotent and must not be called more than once
on the same instance. Doing so will apply the accumulated state
more than once, re-running entry points and <code class="docutils literal notranslate"><span class="pre">import</span></code> lines.</p>
</dd></dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.addsitedir">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">addsitedir</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sitedir</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">known_paths</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.addsitedir" title="Link to this definition"></a></dt>
<dd><p>Add a directory to sys.path and parse the <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> and <code class="file docutils literal notranslate"><span class="pre">.start</span></code>
files found in that directory. Typically used in <a class="reference internal" href="#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="#module-usercustomize" title="usercustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code></a> (see above).</p>
<p>The <em>known_paths</em> argument is an optional set of case-normalized paths
used to prevent duplicate <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> entries. When <code class="docutils literal notranslate"><span class="pre">None</span></code> (the
default), the set is built from the current <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code>.</p>
<p>For batched processing across multiple site directories, build a
<a class="reference internal" href="#site.StartupState" title="site.StartupState"><code class="xref py py-class docutils literal notranslate"><span class="pre">StartupState</span></code></a> explicitly and call <a class="reference internal" href="#site.StartupState.addsitedir" title="site.StartupState.addsitedir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">StartupState.addsitedir()</span></code></a>
on it; that defers <code class="file docutils literal notranslate"><span class="pre">.pth</span></code> and <code class="file docutils literal notranslate"><span class="pre">.start</span></code> processing until a
single <a class="reference internal" href="#site.StartupState.process" title="site.StartupState.process"><code class="xref py py-meth docutils literal notranslate"><span class="pre">StartupState.process()</span></code></a> call, ensuring every <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>
extension is visible before any startup code runs.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Also processes <code class="file docutils literal notranslate"><span class="pre">.start</span></code> files. See <a class="reference internal" href="#site-start-files"><span class="std std-ref">Startup entry points (.start files)</span></a>.</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.getsitepackages">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">getsitepackages</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefixes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#site.getsitepackages" title="Link to this definition"></a></dt>
<dd><p>Return a list containing all global site-packages directories.</p>
<p>For each directory given in <em>prefixes</em> (or <a class="reference internal" href="#site.PREFIXES" title="site.PREFIXES"><code class="xref py py-data docutils literal notranslate"><span class="pre">PREFIXES</span></code></a> if <em>prefixes</em>
is <code class="docutils literal notranslate"><span class="pre">None</span></code>), this function will compute its site-packages subdirectory
depending on the system environment, and will return a list of full paths,
which are not checked for existence.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the optional <em>prefixes</em> parameter.</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.getuserbase">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">getuserbase</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#site.getuserbase" title="Link to this definition"></a></dt>
<dd><p>Return the path of the user base directory, <a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal notranslate"><span class="pre">USER_BASE</span></code></a>. If it is not
initialized yet, this function will also set it, respecting
<span class="target" id="index-9"></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>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="site.getusersitepackages">
<span class="sig-prename descclassname"><span class="pre">site.</span></span><span class="sig-name descname"><span class="pre">getusersitepackages</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#site.getusersitepackages" title="Link to this definition"></a></dt>
<dd><p>Return the path of the user-specific site-packages directory,
<a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">USER_SITE</span></code></a>. If it is not initialized yet, this function will also set
it, respecting <a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal notranslate"><span class="pre">USER_BASE</span></code></a>. To determine if the user-specific
site-packages was added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> <a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">ENABLE_USER_SITE</span></code></a> should be
used.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
</dd></dl>
</section>
<section id="command-line-interface">
<span id="site-commandline"></span><h2>Command-line interface<a class="headerlink" href="#command-line-interface" title="Link to this heading"></a></h2>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> module also provides a way to get the user directories from the
command line:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>site<span class="w"> </span>--user-site
<span class="go">/home/user/.local/lib/python3.11/site-packages</span>
</pre></div>
</div>
<p>If it is called without arguments, it will print the contents of
<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> on the standard output, followed by the value of
<a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal notranslate"><span class="pre">USER_BASE</span></code></a> and whether the directory exists, then the same thing for
<a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">USER_SITE</span></code></a>, and finally the value of <a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">ENABLE_USER_SITE</span></code></a>.</p>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-site-user-base">
<span class="sig-name descname"><span class="pre">--user-base</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-site-user-base" title="Link to this definition"></a></dt>
<dd><p>Print the path to the user base directory.</p>
</dd></dl>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-site-user-site">
<span class="sig-name descname"><span class="pre">--user-site</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-site-user-site" title="Link to this definition"></a></dt>
<dd><p>Print the path to the user site-packages directory.</p>
</dd></dl>
<p>If both options are given, user base and user site will be printed (always in
this order), separated by <a class="reference internal" href="os.html#os.pathsep" title="os.pathsep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.pathsep</span></code></a>.</p>
<p>If any option is given, the script will exit with one of these values: <code class="docutils literal notranslate"><span class="pre">0</span></code> if
the user site-packages directory is enabled, <code class="docutils literal notranslate"><span class="pre">1</span></code> if it was disabled by the
user, <code class="docutils literal notranslate"><span class="pre">2</span></code> if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<ul class="simple">
<li><p><span class="target" id="index-10"></span><a class="pep reference external" href="https://peps.python.org/pep-0370/"><strong>PEP 370</strong></a> – Per user site-packages directory</p></li>
<li><p><span class="target" id="index-11"></span><a class="pep reference external" href="https://peps.python.org/pep-0829/"><strong>PEP 829</strong></a> – Startup entry points and the deprecation of import lines in <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files</p></li>
<li><p><a class="reference internal" href="sys_path_init.html#sys-path-init"><span class="std std-ref">The initialization of the sys.path module search path</span></a> – The initialization of <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></li>
</ul>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> — Site-specific configuration hook</a><ul>
<li><a class="reference internal" href="#path-extensions-pth-files">Path extensions (<code class="file docutils literal notranslate"><span class="pre">.pth</span></code> files)</a></li>
<li><a class="reference internal" href="#startup-entry-points-start-files">Startup entry points (<code class="file docutils literal notranslate"><span class="pre">.start</span></code> files)</a></li>
<li><a class="reference internal" href="#startup-file-examples">Startup file examples</a></li>
<li><a class="reference internal" href="#migrating-from-import-lines-in-pth-files-to-start-files">Migrating from <code class="docutils literal notranslate"><span class="pre">import</span></code> lines in <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files to <code class="docutils literal notranslate"><span class="pre">.start</span></code> files</a></li>
<li><a class="reference internal" href="#module-sitecustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sitecustomize</span></code></a></li>
<li><a class="reference internal" href="#module-usercustomize"><code class="xref py py-mod docutils literal notranslate"><span class="pre">usercustomize</span></code></a></li>
<li><a class="reference internal" href="#readline-configuration">Readline configuration</a></li>
<li><a class="reference internal" href="#module-contents">Module contents</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="annotationlib.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">annotationlib</span></code> — Functionality for introspecting annotations</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="custominterp.html"
title="next chapter">Custom Python Interpreters</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/site.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/site.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="custominterp.html" title="Custom Python Interpreters"
>next</a> |</li>
<li class="right" >
<a href="annotationlib.html" title="annotationlib — Functionality for introspecting annotations"
>previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" >Python Runtime Services</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> — Site-specific configuration hook</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>