Text of peps.python.org › pep-0829 as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 829 – Package Startup Configuration Files | peps.python.org

PEP 829 – Package Startup Configuration Files PEP 829 – Package Startup Configuration Files Author : Barry Warsaw <barry at python.org> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 31-Mar-2026 Python-Version : 3.15 Post-History : 01-Apr-2026 , 13-Apr-2026 , 15-Apr-2026 Resolution : 24-Apr-2026 Table of Contents Abstract Motivation Specification Entry point syntax File Naming and Discovery Error Handling Encoding Future Improvements Rationale Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Open Issues Change History Acknowledgments Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at Startup entry points (.start files) . × See PEP 1 for how to propose changes. Abstract This PEP changes the way packages influence Python’s startup process. Previously controlled through legacy .pth files parsed and executed by the site.py file during interpreter startup, such files are used to extend sys.path and execute package initialization code before control is passed to the first line of user code.

This PEP proposes: Replacing import lines in .pth files with entry point specifications (i.e. pkg.mod:callable ) in .start files. The presence of a matching .start file disables import line processing in the matched .pth file. The sys.path extension functionality of .pth files is retained. Support for import lines in .pth files will be gradually removed: For the first three years (expected to be Python 3.15, 3.16, and 3.17) import line processing in .pth files will remain, except in the presence of a matching .start file.

For the next two years (expected to be Python 3.18 and 3.19), import lines in .pth files will be silently ignored. Afterwards (expected to be Python 3.20 and higher), a warning will be produced for the existence of import lines in .pth files. Motivation Python’s .pth files (processed by Lib/site.py at startup) support two functions: Extending sys.path – Lines in this file (excluding comments and lines that start with import ) name directories to be appended to sys.path .

Relative paths are implicitly anchored at the site-packages directory. Executing arbitrary code – lines starting with import (or import\\t ) are executed immediately by passing the source string to exec() . While there are valid use cases for both, the import line feature is the most problematic because: Code execution is a side effect of the implementation. Lines that start with import can be extended by separating multiple statements with a semicolon.

As long as all the code to be executed appears on the same line, it all gets executed when the .pth file is processed. import lines are executed using exec() during interpreter startup, which opens a broad attack surface. There is no explicit concept of an entry point, which is an established pattern in Python packaging. Packages that require code execution and initialization at startup abuse import lines rather than explicitly declaring entry points.

Specification This PEP proposes the following: Keep the <name>.pth file format, but deprecate import line processing for three years, after which such lines will be disallowed. Keep the current sys.path extension feature of <name>.pth files unchanged. Specifically, absolute paths are used verbatim while relative paths are anchored at the directory in which the .pth file is located. A new file format called <name>.start is added which names entry points conforming to the “colon-form” of pkgutil.resolve_name() arguments.

During the deprecation period, the presence of a <name>.start file matching a <name>.pth file disables the execution of import lines in the <name>.pth file in favor of entry points from the <name>.start file. This provides a migration path straddling Python versions which support this PEP and earlier versions which do not. In this case, warnings about import lines are not printed. During the deprecation period, for any <name>.pth file without a matching <name>.start file, the processing of the former is unchanged, although a warning about import lines is issued when -v (verbose) flag is given to Python.

After the deprecation period import lines in <name>.pth files are ignored and a warning is issued, regardless of whether there is a matching <name>.start file or not. See the How to Teach This section for specific migration guidelines. Both <name>.pth and <name>.start files are processed by the site.py module, just like current .pth files. This means that disabling site.py processing with -S disables processing of both files. site.py start up code is divided into these explicit phases: Find the <name>.pth files (see File Naming and Discovery for additional details) and sort them in alphabetical order by filename.

Parse the <name>.pth files in sorted order, keeping a global list of all path extensions, preserving order file-by-file and then by entry appearance. Duplicates are ignored. During the deprecation period, collect import lines found from <name>.pth files. Processing of these lines is deferred until after <name>.start file scanning. Future extension: apply a global policy filter on the list of path extensions. Append path extensions to sys.path in the global preserved order.

List all <name>.start files (see File Naming and Discovery for additional details) and sort them in alphabetical order by filename. For any <name>.start that matches a previously scanned <name>.pth file, discard all import lines from those matched <name>.pth files. See the How to Teach This section for more details and rationale. Parse the <name>.start files in sorted order, keeping a global list of all entry points, preserving order file-by-file and then by entry appearance.

Duplicates are not ignored . Future extension: apply a global policy filter on the list of entry points. For each entry point in preserved order, use pkgutil.resolve_name() to resolve the entry point into a callable. Call the entry point with no arguments and any return value is discarded. The resolved object is not tested for callability before it is called (and thus any TypeError that might result is reported). In both <name>.pth files and <name>.start files, comment lines (i.e. lines beginning with # as the first non-whitespace character) and blank lines are ignored.

Any other parsing error causes the line to be ignored. Entry point syntax pkgutil.resolve_name() is used to resolve an entry point specification into a callable object. However, in Python 3.14 and earlier, this function accepts two forms, described in the documentation with pseudo-regular expressions: W(.W)* - no colon form W(.W)*:(W(.W)*)? - colon form with optional callable suffix This PEP proposes to only allow pkg.mod:callable form of entry points, and requires that the callable be specified.

See the open issues for further discussion. File Naming and Discovery Packages may optionally install zero or more files of the format <name>.pth and <name>.start . The <name> prefix is arbitrary and need not match the package name or each other, although all else being equal, it is recommended that they do match the package name for clarity. The interpreter does not enforce any constraints on the prefix. Files are processed in alphabetical order. <name>.start files live in the same site-packages directories where <name>.pth files are found today.

The <name>.pth location stays the same. The discovery rules for <name>.start files are the same as with <name>.pth files today. File names that start with a single . (e.g. .start ) and files with OS-level hidden attributes ( UF_HIDDEN , FILE_ATTRIBUTE_HIDDEN ) are excluded. Error Handling During parsing, errors are generally skipped and only reported when -v (verbose) flag is given to Python. Unlike with .pth files currently, processing does not abort for the entire file when an error is encountered.

If a <name>.pth or <name>.start file cannot be opened or

The rest of this page is on the live site.