PyPI malware: malicious Python packages and how to avoid them
PyPI malware is hostile code that comes inside a Python package. It gets onto your machine because someone, you or your agent, installed it. The source can be a lookalike name or a name an AI invented. It can be a public package that pip picks over a private one. It can also be a real project whose publishing access was abused, as in the ultralytics attack. PyPI's advice is that you review before installing. If a bad version ran, make one check described below, then replace the secrets the machine could reach, from a clean device.
Python developers and vibe coders install packages with pip, Python's package installer, all day, and an agent does it for them. Each install runs code from a stranger's account. This page covers how PyPI malware gets in, what the ultralytics case teaches, and a short list of checks. The npm side of the same problem is on npm malware.
01The ultralytics incident
In December 2024 PyPI published an analysis of an attack on the ultralytics project. The attack came through compromised GitHub Actions workflows and a PyPI API token. No flaw in PyPI was used. GitHub Actions is the automation that builds and publishes a project, and an API token is the secret key that lets it publish.
The second round of malicious releases came from an unrevoked PyPI API token that was still available to the GitHub Actions workflow. Closing the first hole was not enough, because the key had not been cancelled. If you publish packages yourself, that is the lesson: after any incident, revoke the old token as well as fixing the workflow.
For everyone else the rule is plain. Not every package and release on PyPI should be treated as trusted, and it is up to you to review what you install.
02How malicious PyPI packages reach a Mac
There is no single trick. The table lists the ways in, with the page for each.
| Way in | What happens | Where to read more |
|---|---|---|
| Abused publishing access | A real project's workflow or token is used to publish a bad release | The section above |
| Lookalike name | A name one typo away from the real one | Typosquatting |
| Invented name | An AI assistant suggests a package that does not exist, and an attacker registers it | Slopsquatting |
| Public package beats a private one | pip searches PyPI and any extra index with no priority, and the best version match wins | Dependency confusion |
| Packages posing as developer tools | npm and PyPI packages stole mnemonic seed phrases and private keys | npm malware |
| A task from a fake recruiter | A Python backdoor, a program that gives an attacker remote control, named InvisibleFerret is used in later stages of the attack | Fake job interview malware |
03How pip chooses between sources
pip searches PyPI and any extra locations given with --extra-index-url, and there is no priority among the places searched. The --index-url option sets the base index, and --extra-index-url adds more. pip pools every source it is configured with and picks the best version. So a public package with the same name as a private one and a higher version can win. If your team has private packages, use one index only unless you have a reason to add another.
04A name an AI invented
An assistant can suggest a package that does not exist. In one study the average share of hallucinated packages was at least 5.2% for commercial models and 21.7% for open-source models. The risk is that an attacker registers the missing name before you notice. Auto mode in Claude Code allows installing dependencies declared in lock files or manifests by default. A lock file is where exact package versions are recorded. So an invented name in a requirements file may be installed without a pause.
05Is PyPI safe to use?
PyPI is the public index, and anyone with an account can publish to it. That is why the advice is to review what you install: not every package and release on PyPI should be treated as trusted. The ultralytics attack did not use a flaw in PyPI itself. So PyPI malware is mostly a question of which package you let in and which keys sit on the machine where it runs. Reading a project's page for two minutes before the first install catches most lookalike and invented names, and the checklist below makes that routine.
06Checklist before you install a Python package
- Read the name twice. Compare it with the project's own page and README. A name one letter off is typosquatting.
- Did you choose it? If an assistant added it, search for the project on its own site first.
- Know where pip will look. Look for
--index-urland--extra-index-urlin your pip configuration and in the install commands your project uses, because every location is searched with no priority. pip's docs on configuration show where pip reads its settings. - Review the project. You are the one who has to review use of software from PyPI. On the package's page on pypi.org, check who maintains it, how old it is and whether the linked repo matches.
- Pin what you install. Pinning means writing one exact version in your requirements file, so a surprise new release is not pulled in. The syntax is in pip's install docs.
- Install where a mistake costs less. A container, a VM or a throwaway folder keeps a bad install away from your keys. The dev container page shows one way for agent work.
For a repo you were sent rather than found, use malware in GitHub repositories.
07PyPI malware and your agent
An agent changes who types the install command. You no longer read each pip install line as it happens, so the review has to move earlier. Look when the agent proposes a new name, and read the diff that adds it to a requirements file. Ask the agent where it got the name, open the project's own page, and only then let the install go ahead. If the answer is vague, the name is a guess, and a guess is exactly what slopsquatting waits for.
A sandbox limits damage but does not check the package. In Codex, for example, package managers inherit the sandbox's limits.
08If a bad package already ran
Do not wait to prove it. If the same Mac also installed npm packages, first look for ~/Library/LaunchAgents/com.user.gh-token-monitor.plist. The npm side of the Mini Shai-Hulud campaign leaves that file, and its program fires when the GitHub token it checks is revoked, from any device. If the file is there, follow the order on the Shai-Hulud page before you revoke anything. Otherwise replace credentials and sessions that the machine could reach, from a clean device. Start with the tokens and keys the Python project and your shell could read, such as API tokens, cloud keys and GitHub access. A token is a secret string that lets a program act as you. After replacing them, check the logs that show where the old ones were used. The steps are on leaked API key and the infostealer check.
One habit covers most PyPI malware: slow down at the moment a new name appears, whoever added it. That includes names that arrive inside a requirements file from a repo you cloned, a tutorial you pasted, or a colleague's branch. Open the project's page, check that it is the one you meant, and then install. It takes a minute per new name.
The npm worm Shai-Hulud is described on Shai-Hulud. The wider history is on npm supply chain attack.
To see what a package install starts on your Mac, the free, open-source core of Artificial Immunity watches program starts and reports what it finds.
FAQ
How safe is PyPI?
Not every package and release on PyPI should be treated as trusted, and you have to review your use of software from PyPI before installing. The ultralytics attack did not use a flaw in PyPI.
What is PyPI used for?
It is the public index that pip searches for Python packages. Companies can add their own sources with --extra-index-url.
What are malicious PyPI packages?
They are Python packages that carry hostile code. Examples include packages posing as developer tools that stole seed phrases and private keys.
Can a well-known PyPI project ship malware?
Yes. In the ultralytics case the attack came through compromised GitHub Actions workflows and a PyPI API token. A second round of malicious releases used a token that had not been revoked.
How do I check a Python package before installing it?
Read the package name carefully, check where pip will look for it, and review the project before you install. The full list is in the checklist section of this page.
What if I already installed a bad package?
First look for the file ~/Library/LaunchAgents/com.user.gh-token-monitor.plist; the npm side of the Mini Shai-Hulud campaign leaves it, and its program fires when the GitHub token it checks is revoked, from any device. If it is there, follow the order on the Shai-Hulud page. If not, replace the credentials and sessions the machine could reach, working from a clean device; the detail is in leaked API key.
Related guides
Sources
- PyPI blog, ultralytics attack analysis
- pip docs, pip install
- Socket glossary, dependency confusion
- Socket, wallet-stealing npm and PyPI packages
- Socket, slopsquatting
- arXiv, package hallucination study
- Microsoft, Contagious Interview
- Wikipedia, typosquatting
- Claude Code docs, permission modes
- pip docs, configuration
- Artificial Immunity