PyPI packages that run code every time Python starts

Published 20 November 2026 · Data as of 13 November 2026

Scripts and results for this post on GitHub

PyPI packages that run code every time Python startsData as of 13 Nov 2026Packages that ship a.pth file with animport line736of 354,763 indexed projects684run it on every Python startafter a normal installWhat runs at startup244packages run their own code440only old setuptools namespaceboilerplateReady for Python3.15's .start files(PEP 829)13of the 244 that run their own codeThree PyPI attacks in 2026 used a .pth file: litellm 1.82.8 in March, litellm 1.107.0in October and agent-framework 1.26.1 and 1.26.2 in November. Installing the packagewas enough to run the credential stealer.Latest release of 354,763 PyPI projects; each listed .pth file downloaded and read.py-code.org
PyPI packages that run codeevery time Python startsData as of 13 Nov 2026Packages that ship a .pth file with an import line736of 354,763 indexedprojects684run it on everyPython start aftera normal installWhat runs at startup244packages run theirown code440only oldsetuptoolsnamespaceboilerplateReady for Python 3.15's .start files (PEP 829)13of the 244 that run their own codeThree PyPI attacks in 2026 used a .pthfile: litellm 1.82.8 in March, litellm1.107.0 in October and agent-framework1.26.1 and 1.26.2 in November.Installing the package was enough torun the credential stealer.Latest release of 354,763 PyPI projects;each listed .pth file downloaded andread. py-code.org

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

QuestionAnswerKey number
How many PyPI packages ship a .pth file with an import line?736 of the 354,763 indexed projects684 of them run it on every Python start
What do those 684 run?244 run their own code, 440 only old setuptools namespace boilerplate244 packages
Which widely used packages run their own code?setuptools, coverage, coloredlogs, pywin32 and 68 more of the 60,000 most downloaded688 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 run52 packages
How many are ready for Python 3.15's .start files?13 of the 244 packages that run their own code5.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 import followed by a space or a tab is run with exec(). 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 to exec() 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 as google, collective or flytekitplugins), older setuptools writes a -nspkg.pth file with a long import sys, types, os;… line that sets up the shared namespace. It imports no code from the package. The most downloaded of these is google-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.

What the .pth files in PyPI packages doprojectsRuns its own code244Namespace boilerplate only440Runs on Windows only17Never runs35
The 736 PyPI projects whose latest release has a .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.

PackageDownloads, 30 days.pth fileWhat the startup line doesWhen it acts
setuptools467.5Mdistutils-precedence.pthAdds an import hook so that import distutils gets the copy setuptools shipsAlways, unless SETUPTOOLS_USE_DISTUTILS=stdlib
coverage181.8Ma1_coverage.pthStarts coverage measurement in the new processOnly with a variable (COVERAGE_PROCESS_START)
coloredlogs21.6Mcoloredlogs.pthTurns on coloured log outputOnly with a variable (COLOREDLOGS_AUTO_INSTALL)
pywin328.1Mpywin32.pthAdds pywin32's folders to sys.path and its DLL folder to the DLL search pathAlways
nvidia-cutlass-dsl1.6Mnvidia_cutlass_dsl_packages.pthImports the package and puts its dsl_packages folder first on sys.pathAlways
ibm-db1.5Mibm_db_dll.pthAdds the IBM CLI driver's DLL folder to the DLL search pathAlways, on Windows only
pynvml1.0M_pynvml_redirector.pthAdds an import hook that warns that pynvml is deprecatedAlways
cmeel0.6Mcmeel.pthAdds cmeel's cmeel.prefix folders to sys.pathAlways
snowflake.-legacy0.4Msnowflake.pthImports the snowflake package and adds the legacy API to itAlways
modin0.4Mmodin-autoimport-pandas.pthImports pandasOnly with a variable (__MODIN_AUTOIMPORT_PANDAS__)
better-exceptions0.4Mbetter_exceptions_hook.pthReplaces the exception hook with better_exceptions' formatterOnly with a variable (BETTER_EXCEPTIONS)
future-fstrings0.3Maaaaa_future_fstrings.pthRegisters a source codec that lets old Pythons read f-stringsAlways
pip-system-certs0.2Mpip_system_certs.pthInjects truststore so requests and pip use the system's certificatesAlways
urllib3-future0.2Murllib3_future.pthCopies its own files over the urllib3 folderAlways, when the folder is writable
load-dotenv0.2Mload_dotenv.pthImports python-dotenv, and loads a .env fileThe import always, the .env only with LOAD_DOTENV
Most downloaded packages whose .pth fileruns their own code at startupmillion downloads in 30 dayssetuptools467.5coverage181.8coloredlogs21.6pywin328.1nvidia-cutlass-dsl1.6ibm-db1.5pynvml1.0cmeel0.6snowflake.-legacy0.4modin0.4
The ten most downloaded packages whose .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 urllib3 folder in site-packages when Python starts and the folder is writable. The .pth file explains why: "Python packaging has no native concept of package replacement". To keep both packages separate, it says to reinstall with URLLIB3_NO_OVERRIDE=1 set.
  • pip-system-certs (0.2M) injects truststore into Python's SSL setup, so requests and 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.Union in the standard library. It skips all of this when NO_SPHINX_JINJA2_COMPAT is 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 imports pynvml, and numba-cuda's sends numba.cuda imports to the numba_cuda package.
  • iac-guard-v sets sys.dont_write_bytecode = True, which stops every Python process in the environment from writing .pyc files.

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 into site-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 as adauto_post_install.pth and deepstrain_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: two acryl-datahub files 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.pth with a base64-encoded script that collected SSH keys, cloud credentials and .env files 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 is import 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.pth and af_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: import lines still run, unless a .start file 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: import lines are ignored without a warning.
  • Python 3.20: ignored import lines 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 -S to start Python without the site module. No .pth file runs, but site-packages is not on sys.path either, so use it to test, not as a fix.
  • On Python 3.15, run python -v -c pass 2>&1 | grep deprecated to see which files still use import lines.

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 .pth file in that release file with a line that starts with import. We downloaded all 748 again and confirmed that each has a line that site runs (import followed 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.pth files. 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