PEP 829 – Package Startup Configuration Files | peps.python.org
Following system colour scheme
Selected dark colour scheme
Selected light colour scheme
PEP 829 – Package Startup Configuration Files
PEP 829 – Package Startup Configuration Files
Author:<br>Barry Warsaw<br>Discussions-To:<br>Discourse thread<br>Status:<br>Final<br>Type:<br>Standards Track<br>Created:<br>31-Mar-2026<br>Python-Version:<br>3.15<br>Post-History:<br>01-Apr-2026,<br>13-Apr-2026,<br>15-Apr-2026<br>Resolution:<br>24-Apr-2026
Table of Contents<br>Abstract
Motivation
Specification<br>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.<br>Previously controlled through legacy .pth files parsed and executed by the<br>site.py file during interpreter startup, such files are used to extend<br>sys.path and execute package initialization code before control is passed<br>to the first line of user code.
This PEP proposes:
Replacing import lines in .pth files with entry point specifications<br>(i.e. pkg.mod:callable) in .start files.
The presence of a matching .start file disables import line<br>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)<br>import line processing in .pth files will remain, except in the<br>presence of a matching .start file.
For the next two years (expected to be Python 3.18 and 3.19), import<br>lines in .pth files will be silently ignored.
Afterwards (expected to be Python 3.20 and higher), a warning will be<br>produced for the existence of import lines in .pth files.
Motivation
Python’s .pth files (processed by Lib/site.py at startup)<br>support two functions:
Extending sys.path – Lines in this file (excluding comments<br>and lines that start with import) name directories to be<br>appended to sys.path. Relative paths are implicitly anchored at<br>the site-packages directory.
Executing arbitrary code – lines starting with import (or<br>import\\t) are executed immediately by passing the source string<br>to exec().
While there are valid use cases for both, the import line feature is the<br>most problematic because:
Code execution is a side effect of the implementation. Lines that<br>start with import can be extended by separating multiple<br>statements with a semicolon. As long as all the code to be<br>executed appears on the same line, it all gets executed when the<br>.pth file is processed.
import lines are executed using exec() during interpreter<br>startup, which opens a broad attack surface.
There is no explicit concept of an entry point, which is an established<br>pattern in Python packaging. Packages that require code execution and<br>initialization at startup abuse import lines rather than explicitly<br>declaring entry points.
Specification
This PEP proposes the following:
Keep the .pth file format, but deprecate import line<br>processing for three years, after which such lines will be disallowed.
Keep the current sys.path extension feature of .pth files<br>unchanged. Specifically, absolute paths are used verbatim while relative<br>paths are anchored at the directory in which the .pth file is located.
A new file format called .start is added which names entry points<br>conforming to the “colon-form” of pkgutil.resolve_name() arguments.
During the deprecation period, the presence of a .start file<br>matching a .pth file disables the execution of import lines in<br>the .pth file in favor of entry points from the .start<br>file. This provides a migration path straddling Python versions which<br>support this PEP and earlier versions which do not. In this case, warnings<br>about import lines are not printed.During the deprecation period, for any .pth file without a<br>matching .start file, the processing of the former is unchanged,<br>although a warning about import lines is issued when -v (verbose)<br>flag is given to Python.
After the deprecation period import lines in .pth files are<br>ignored and a warning is issued, regardless of whether there is a matching<br>.start file or not.
See the How to Teach This section for specific migration guidelines.
Both .pth and .start files are processed by the<br>site.py module, just like current .pth files. This means that<br>disabling site.py processing with -S disables processing of<br>both files.
site.py start up code is divided into these explicit phases:
Find the .pth files (see File Naming and Discovery for additional details)<br>and sort them in alphabetical order by filename.
Parse the .pth files in sorted order, keeping a global list of<br>all path extensions,...