PyPI can refuse a name even when you see no project by that name. The help page lists four reasons: it matches a standard library module, it is too similar to an existing project, administrators prohibited it, or another user registered it without making a release. Check all four before you commit.
The four reasons
| Reason | What it means | What you do |
|---|---|---|
| Standard library clash | The name conflicts with a Python standard library module from version 2.5 to now | Pick a different name |
| Too similar to an existing project | PyPI treats it as confusable | Choose a clearly distinct name |
| Prohibited by administrators | For example a common typo of a command, which should not surprise users with a malicious package | Pick a different name |
| Registered with no releases | Another user holds the name but never published | Follow the name transfer process |
The first three exist to protect users. The fourth is the one people hit when a name looks free and is not.
How names are compared
Names are normalized before comparison. The Packaging guide says comparison is case insensitive and treats any run of hyphens, underscores or periods as equal. So Cool-Stuff, cool.stuff and COOL_STUFF are all the same project. If you register one, users can ask for it by any of those spellings. Our post on name normalization goes deeper.
The name format is also restricted. A valid name uses only ASCII letters, numbers, periods, underscores and hyphens, and must start and end with a letter or number.
A name checking routine
- Normalize your candidate. Lowercase it and collapse runs of separators into one hyphen.
- Search PyPI for the normalized form. Also try small variations such as plural forms.
- Check the standard library. Do not choose a name that matches a module users import every day.
- Check that the import name makes sense. The distribution name and the import name are separate. The guide notes PyPI does not enforce any relationship between them, so a mismatch is legal but confusing.
- Say the name out loud and search it. If search results are dominated by something else, expect confusion.
- Check other places you depend on: your repository name, domain and documentation host.
What not to do
Do not choose a name one character away from a popular package, even by accident. Users who mistype will install yours, and the help page lists being too similar to an existing project as a reason for refusal. Pick something plainly different.
If the name looks abandoned
The help page says to follow the "How to request a name transfer" section of PEP 541. We walk through the rules in how to claim an abandoned PyPI name. Do not assume a quiet name is yours to take.
The tutorial's advice
The packaging tutorial suggests putting your username in the example project name so it does not clash with other people's uploads. For a real package, it says choose a memorable and unique name, since you cannot use an existing one.
Safeguard's dependency scanning matches package names against known data, so a clear name also helps your users find accurate results. You can try a free scan.
Quick check
Can I use a name that matches a standard library module?
No. PyPI lists a standard library conflict from Python 2.5 onward as a reason a name is refused.
The name seems unused. Why is it taken?
Another user may have registered it without a release. Use the PEP 541 transfer process rather than waiting.
Does my import name have to match the PyPI name?
No, but a mismatch confuses users. PyPI does not enforce a link between the two.
Sources
- PyPI help, FAQ
- Names and normalization, Python Packaging User Guide
- Writing your pyproject.toml, Python Packaging User Guide
- Distribution package vs. import package, Python Packaging User Guide
- Packaging Python Projects, Python Packaging User Guide
Last reviewed: 19 October 2026.
