PyPI packages that run code every time Python starts
Scripts and results for this post on GitHub
In 2026, three attacks on PyPI packages used the same trick. The malicious releases of litellm (in March and again in October) and Microsoft's agent-framework (in November) each added a .pth file. Python runs the import lines in these files every time it starts, so installing the package was enough to start the credential stealer. Nobody had to import the package.
Many ordinary packages use the same feature. py-code.org reads the code in the latest release of 354,763 PyPI projects. We downloaded every .pth file with an import line that the index lists, 748 files from 736 projects, and checked what each one does and whether Python actually runs it.
The short answer
| Question | Answer | Key number |
|---|---|---|
How many PyPI packages ship a .pth file with an import line? | 736 of the 354,763 indexed projects | 684 of them run it on every Python start |
| What do those 684 run? | 244 run their own code, 440 only old setuptools namespace boilerplate | 244 packages |
| Which widely used packages run their own code? | setuptools, coverage, coloredlogs, pywin32 and 68 more of the 60,000 most downloaded | 688 million downloads a month between them |
| How many put the file where Python never reads it on Linux or macOS? | 17 run only on Windows, 35 never run | 52 packages |
How many are ready for Python 3.15's .start files? | 13 of the 244 packages that run their own code | 5.3% |
Verdict: startup code is rare on PyPI: 684 of 354,763 projects ship it, and 440 of those only run namespace boilerplate. The most downloaded packages that run their own code do little: setuptools adds an import hook, and coverage and coloredlogs do nothing unless you set an environment variable. But Python gives no warning when a package adds a .pth file, which is why attackers use it. Python 3.15 starts phasing out import lines, and only 13 of the 244 packages that run their own code have moved to the replacement.
What is a .pth file in Python?
A .pth file is a small text file in site-packages. When Python starts, its site module reads every .pth file in each site directory, sorted by file name. The site documentation describes two kinds of line:
- A line with a path adds that folder to
sys.path, so modules in it can be imported. - A line that starts with
importfollowed by a space or a tab is run withexec(). The documentation says this is kept "for backward compatibility". The line can hold more than an import: several statements separated by semicolons, or a call toexec()with a whole program in a string.
The second kind runs before your script, in every Python process in that environment: your program, pip, pytest, a language server, a one-line python -c. Because the files run in name order, some packages pick names to run first or last: coverage ships a1_coverage.pth, future-fstrings ships aaaaa_future_fstrings.pth, and cuml-cu12 ships _zz_cuml_accel.pth.
The .pth files this post is about have nothing to do with PyTorch. PyTorch also uses the .pth extension for saved model weights, which are loaded with torch.load, not by Python at startup.
684 PyPI packages run a .pth file on every Python start
Of the 736 projects with a .pth file that has an import line, 684 install it at the top of site-packages, where every Python start runs it. They fall into two groups:
- 244 packages run their own code. The line imports a module of the package, or runs code written into the line itself.
- 440 packages run only namespace boilerplate. When a project declares a
pkg_resources-style namespace package (such asgoogle,collectiveorflytekitplugins), older setuptools writes a-nspkg.pthfile with a longimport sys, types, os;…line that sets up the shared namespace. It imports no code from the package. The most downloaded of these isgoogle-cloud-aiplatform(70.8M downloads a month). 38 of these files were built with Python 2.7, as their names show (-py2.7-nspkg.pth). The packaging guide calls these pre-PEP 420 methods obsolete.
The other 52 packages ship the file somewhere Python does not read it on Linux or macOS. They are covered below.
.pth file with an import line, by what that file does after a normal install. A project with both its own code and namespace boilerplate counts as running its own code.The most downloaded: setuptools, coverage and coloredlogs
72 of the 244 packages that run their own code are among the 60,000 most downloaded on PyPI. Together they had 688 million downloads in the 30 days before the scan, and setuptools and coverage account for 649 million of them. The table shows the 15 most downloaded and what their startup line does. We read each line, and the module it imports, by hand.
| Package | Downloads, 30 days | .pth file | What the startup line does | When it acts |
|---|---|---|---|---|
setuptools | 467.5M | distutils-precedence.pth | Adds an import hook so that import distutils gets the copy setuptools ships | Always, unless SETUPTOOLS_USE_DISTUTILS=stdlib |
coverage | 181.8M | a1_coverage.pth | Starts coverage measurement in the new process | Only with a variable (COVERAGE_PROCESS_START) |
coloredlogs | 21.6M | coloredlogs.pth | Turns on coloured log output | Only with a variable (COLOREDLOGS_AUTO_INSTALL) |
pywin32 | 8.1M | pywin32.pth | Adds pywin32's folders to sys.path and its DLL folder to the DLL search path | Always |
nvidia-cutlass-dsl | 1.6M | nvidia_cutlass_dsl_packages.pth | Imports the package and puts its dsl_packages folder first on sys.path | Always |
ibm-db | 1.5M | ibm_db_dll.pth | Adds the IBM CLI driver's DLL folder to the DLL search path | Always, on Windows only |
pynvml | 1.0M | _pynvml_redirector.pth | Adds an import hook that warns that pynvml is deprecated | Always |
cmeel | 0.6M | cmeel.pth | Adds cmeel's cmeel.prefix folders to sys.path | Always |
snowflake.-legacy | 0.4M | snowflake.pth | Imports the snowflake package and adds the legacy API to it | Always |
modin | 0.4M | modin-autoimport-pandas.pth | Imports pandas | Only with a variable (__MODIN_AUTOIMPORT_PANDAS__) |
better-exceptions | 0.4M | better_exceptions_hook.pth | Replaces the exception hook with better_exceptions' formatter | Only with a variable (BETTER_EXCEPTIONS) |
future-fstrings | 0.3M | aaaaa_future_fstrings.pth | Registers a source codec that lets old Pythons read f-strings | Always |
pip-system-certs | 0.2M | pip_system_certs.pth | Injects truststore so requests and pip use the system's certificates | Always |
urllib3-future | 0.2M | urllib3_future.pth | Copies its own files over the urllib3 folder | Always, when the folder is writable |
load-dotenv | 0.2M | load_dotenv.pth | Imports python-dotenv, and loads a .env file | The import always, the .env only with LOAD_DOTENV |
.pth file runs their own code at every Python start, with their downloads in the 30 days before the scan.How to read the table: "Only with a variable" means the startup code does nothing until you set an environment variable, such as COVERAGE_PROCESS_START for coverage. Python still opens the file and runs the check on every start. "Always" means the code changes something in every Python process in that environment.
The most downloaded case is setuptools. Its distutils-precedence.pth adds an import hook so that import distutils gets the copy of distutils that setuptools ships. The setuptools documentation says this copy is "enabled by default" since setuptools 60, and that SETUPTOOLS_USE_DISTUTILS=stdlib turns it off. coverage added its .pth file in version 7.12.1b1, so that measuring subprocesses works when site-packages is read-only, according to its changelog. The file does nothing unless COVERAGE_PROCESS_START or COVERAGE_PROCESS_CONFIG is set.
Some startup hooks change other packages
Most of the startup lines in the table adjust the package's own setup. A few change other packages or Python itself, in every process, whether or not you use the package that did it:
- urllib3-future (0.2M downloads a month) copies its own files over the
urllib3folder insite-packageswhen Python starts and the folder is writable. The.pthfile explains why: "Python packaging has no native concept of package replacement". To keep both packages separate, it says to reinstall withURLLIB3_NO_OVERRIDE=1set. - pip-system-certs (0.2M) injects
truststoreinto Python's SSL setup, sorequestsand pip use the operating system's certificates. - sphinx-jinja2-compat (0.1M) imports and patches Jinja2 and MarkupSafe at startup, and on Python 3.10 and later sets
types.Unionin the standard library. It skips all of this whenNO_SPHINX_JINJA2_COMPATis set. - pynvml (1.0M) and numba-cuda (0.1M) add an import hook to
sys.meta_path. pynvml's hook prints a deprecation warning when something importspynvml, and numba-cuda's sendsnumba.cudaimports to thenumba_cudapackage. - iac-guard-v sets
sys.dont_write_bytecode = True, which stops every Python process in the environment from writing.pycfiles.
Why: a wheel has no install script, so a package cannot run code when it is installed. A .pth file lets an installed package run code at startup without being imported. That is why debuggers, coverage tools and auto-instrumentation agents use it, and why attackers use it too.
52 packages put the .pth file where it does not run
Python reads .pth files only when they sit directly in a site directory. 52 packages ship one somewhere else:
- 17 run only on Windows. They put the file in the wheel's
.data/data/folder, which pip installs into the root of the environment rather than intosite-packages. On Windows the root of the environment is also a site directory, so the file runs there. On Linux and macOS it is never read. Several of these files are named like install steps, such asadauto_post_install.pthanddeepstrain_post_install.pth. - 35 never run after a normal install. Some keep the file inside a package folder, for example in a folder named
observer_template. Others packed files by mistake: twoacryl-datahubfiles sit under a temporary build folder,tmp/build-env-…/lib/python3.10/site-packages/. A few wheels contain files from a virtual environment, or a copy of another program's Python installation.
Tip: to check where a .pth file in your own wheel will land, list the wheel with unzip -l. Only a file at the top level of the wheel, or at the top of <name>.data/purelib/ or .data/platlib/, ends up in site-packages on every platform.
How the 2026 litellm and agent-framework attacks used .pth files
The three attacks followed the same pattern. An attacker got access to the package's release process, published a version with a .pth file and a payload, and the payload ran the next time any Python process started in an environment where that version was installed:
- litellm 1.82.8, March 2026. The release shipped
litellm_init.pthwith a base64-encoded script that collected SSH keys, cloud credentials and.envfiles and sent them to an external server (litellm issue #24521). PyPI says the publishing token was exposed through a compromised Trivy dependency, that the malicious litellm releases were available for 2 hours 32 minutes, and that they were downloaded over 119,000 times (PyPI incident report). Version 1.82.7 also contained malware, but in a module that only ran when litellm was imported (Simon Willison). - litellm 1.107.0, October 2026. An attacker changed litellm's release workflow and published a version with
cook.pth, whose single line isimport cook. It was on PyPI for about two hours. Microsoft writes that "an application did not need to import LiteLLM for the payload to run" (Microsoft, LiteLLM). - agent-framework 1.26.1 and 1.26.2, 17 November 2026. Microsoft's agent framework got two malicious releases with
agent_framework_meta.pthandaf_runtime_diag.pth. They stole environment variables, credential files and Azure and GitHub Actions tokens. Wiz reports that both were gone from PyPI by 21:30 UTC, under an hour after the first was published (GitHub advisory, Wiz).
Key point: in all three, installing the package was enough. Uninstalling the package afterwards does not clean the environment: Microsoft notes that "removing the package or a release tag is not sufficient recovery", and LiteLLM told users to delete cook.pth, cook.py and sitecustomize.py and to rotate the credentials the environment could reach. Microsoft maps the technique to MITRE ATT&CK T1546.018, Python startup hooks.
Python 3.15 deprecates import lines in .pth files (PEP 829)
Barry Warsaw opened a CPython issue to remove code execution from .pth files in 2018 (issue 78125), and PEP 829, accepted in April 2026, sets the plan. It says that running import lines with exec() at startup "opens a broad attack surface", and that "code execution is a side effect of the implementation". From Python 3.15, a package can ship a <name>.start file that lists entry points, one package.module:function per line, instead. The timeline in the PEP and the site documentation:
- Python 3.15 to 3.17:
importlines still run, unless a.startfile with the same name exists. Then they are ignored, so a package can ship both files and work on old and new Pythons. - Python 3.18 and 3.19:
importlines are ignored without a warning. - Python 3.20: ignored
importlines produce a warning.
We tried this on Python 3.15.0rc2. A .pth file with an import line still runs, with no message. With python -v, Python prints that the import lines "are deprecated, use entry points in a … .start file instead". After we added a .start file with the same name, Python ran its entry point and ignored the import line.
Only 13 of the 244 packages that run their own code ship a .start file today, among them autowrapt, atpublic-install, django-service-urls and six karellen-* toolchain packages. The others, including setuptools and coverage, will stop running their startup code on Python 3.18 unless they add one. The 440 namespace packages will lose their -nspkg.pth lines at the same time. We have not tested whether these packages still import without the lines.
How to check which .pth files run in your environment
This command lists every .pth file with an import line in the site directories of the Python you run it with. Run it inside each virtual environment you want to check:
python -c "import site, glob, os; dirs = site.getsitepackages() + [site.getusersitepackages()]; [print(f) for d in dirs for f in sorted(glob.glob(os.path.join(d, '*.pth'))) if any(l.startswith(('import ', 'import\t')) for l in open(f, encoding='utf-8', errors='replace'))]"
In a virtual environment made with uv venv you will see at least _virtualenv.pth, which uv adds itself (uv 0.12.13 in our test). On Fedora, the system Python also has abrt3.pth, from the ABRT crash reporter. Other things you can do:
- Open each file it lists and read the line, then the module it imports.
- Run
python -Sto start Python without thesitemodule. No.pthfile runs, butsite-packagesis not onsys.patheither, so use it to test, not as a fix. - On Python 3.15, run
python -v -c pass 2>&1 | grep deprecatedto see which files still useimportlines.
To see which PyPI packages ship such a file without installing anything, query the index on Hugging Face with DuckDB. This query lists them by downloads on the pinned 13 November 2026 snapshot. It includes the files that never run, such as acryl-datahub's:
-- PyPI projects whose latest release has a .pth file with an import line, -- most downloaded first (downloads_30d is empty outside the 60,000 most downloaded) SELECT t.project, t.pth, p.downloads_30d FROM 'hf://datasets/pypi-data/py-code@9d81d70d6519d77f4dee4811b3e3a5d88379c17d/pth_files.parquet' t JOIN 'hf://datasets/pypi-data/py-code@9d81d70d6519d77f4dee4811b3e3a5d88379c17d/projects.parquet' p USING (project) ORDER BY p.downloads_30d DESC NULLS LAST, t.project, t.pth LIMIT 12;
It returned:
┌───────────────────────────┬──────────────────────────────────────────────────────────────────────────┬───────────────┐ │ project │ pth │ downloads_30d │ │ varchar │ varchar │ int64 │ ├───────────────────────────┼──────────────────────────────────────────────────────────────────────────┼───────────────┤ │ setuptools │ distutils-precedence.pth │ 467506191 │ │ coverage │ a1_coverage.pth │ 181756312 │ │ google-cloud-aiplatform │ google_cloud_aiplatform-2.9.0-py3.12-nspkg.pth │ 70848521 │ │ coloredlogs │ coloredlogs.pth │ 21574132 │ │ pywin32 │ pywin32.pth │ 8087734 │ │ google-generativeai │ google_generativeai-0.8.6-py3.13-nspkg.pth │ 7074908 │ │ acryl-datahub │ tmp/build-env-0gc7l757/lib/python3.10/site-packages/datahub_force_pure_… │ 6806934 │ │ acryl-datahub │ tmp/build-env-0gc7l757/lib/python3.10/site-packages/datahub_setproctitl… │ 6806934 │ │ functions-framework │ functions_framework-3.10.2-py3.12-nspkg.pth │ 4558411 │ │ snowflake-snowpark-python │ snowflake_snowpark_python-1.56.0-py3.11-nspkg.pth │ 2595278 │ │ nvidia-cutlass-dsl │ nvidia_cutlass_dsl_packages.pth │ 1623552 │ │ ibm-db │ ibm_db_dll.pth │ 1474574 │ └───────────────────────────┴──────────────────────────────────────────────────────────────────────────┴───────────────┘ 12 rows 3 columns
The scripts behind every number in this post, including the one that downloads and reads each .pth file, are in the pypi-data/blog repository with their results.
How the numbers were counted
- Which projects. The index holds the latest release of 354,763 projects: every project released between 13 November 2025 and 13 November 2026, plus the 60,000 most downloaded projects even when their latest release is older. For each project it reads one file: a pure-Python wheel, then a platform wheel, then the source distribution.
- Which .pth files. The index lists every
.pthfile in that release file with a line that starts withimport. We downloaded all 748 again and confirmed that each has a line thatsiteruns (importfollowed by a space or a tab). - Whether it runs. We judged this from the file's path in the wheel, following how pip installs wheels, and did not install the packages. A source distribution counts as "never", because it installs only what its build script copies.
- What it does. A file counts as namespace boilerplate when its line is the one setuptools writes for
-nspkg.pthfiles. Everything else counts as the package's own code. We read the line and the module it imports for the packages named in this post only, not for all 244. - Downloads. Download counts are for the 30 days before the scan, from ClickHouse's public PyPI dataset, and exist only for the 60,000 most downloaded projects.
Frequently asked questions
What is a .pth file in Python?
A .pth file is a text file in site-packages that Python's site module reads at startup. A line with a path adds that folder to sys.path. A line that starts with import followed by a space or a tab is run as code.
Is a Python .pth file the same as a PyTorch .pth file?
No. PyTorch uses the .pth extension for saved model weights, which you load with torch.load. The .pth files in site-packages are configuration files that Python reads every time it starts.
Does a .pth file run if I never import the package?
Yes. Python runs the import lines in every .pth file that sits directly in site-packages when it starts, before your own code. That is why the malicious litellm and agent-framework releases in 2026 ran their stealers as soon as any Python process started after the install.
How did the litellm supply chain attack work?
In March 2026, litellm 1.82.8 shipped a litellm_init.pth file with a base64-encoded script that collected SSH keys, cloud credentials and .env files and sent them to an external server. In October 2026, litellm 1.107.0 shipped cook.pth, whose one line imported a credential stealer. In both releases, installing the package was enough to run the stealer.
Are .pth files deprecated in Python 3.15?
Only their import lines. PEP 829 deprecates them in Python 3.15 and adds .start files with entry points as the replacement. Python 3.18 will ignore import lines, and lines that add a path to sys.path keep working.
How many PyPI packages run code from a .pth file?
684 of the 354,763 projects in the py-code.org index install a .pth file that runs on every Python start. 244 of them run their own code, and 440 only run setuptools namespace boilerplate.
Sources
- py-code.org dataset on Hugging Face, revision
9d81d70d(13 November 2026) - pypi-data/blog, the scripts and results for this post
- Python documentation: site, site-specific configuration hook
- PEP 829: Package Startup Configuration Files (accepted April 2026)
- CPython issue 78125: Deprecate and remove code execution in pth files (2018)
- Python Packaging User Guide: packaging namespace packages
- setuptools: porting from distutils
- coverage.py change history and measuring subprocesses
- litellm issue #24521: litellm 1.82.8 contains litellm_init.pth (March 2026)
- PyPI: incident report on the LiteLLM and Telnyx supply-chain attacks (April 2026)
- Simon Willison: malicious litellm_init.pth in litellm 1.82.8 (March 2026)
- LiteLLM: release v1.107.0 compromised (October 2026)
- Microsoft Security: inside the LiteLLM 1.107.0 supply chain compromise (October 2026)
- GitHub advisory GHSA-764m-3ppc-5m73: malicious code in agent-framework (November 2026)
- Wiz: malicious version of Microsoft's agent-framework published to PyPI (November 2026)
- ClickHouse PyPI downloads (ClickPy)