PyPI refuses an upload when the filename, which combines project name, version and distribution type, was used before. This holds even if the file was deleted or the project was removed and recreated. The fix is to bump the version and upload again. You cannot replace the old file.
What PyPI documents
The PyPI help page lists three reasons for the filename errors: the filename has been used and the file still exists, the filename has been used but the file no longer exists, or a file with the exact same content exists. PyPI does not allow a filename to be reused, even after a project has been deleted and recreated. A distribution filename is the combination of project name, version number and distribution type, which means a given distribution for a given release of a given project will always resolve to the same file.
Why it works this way
Pinned installs and hash checking depend on it. If a name and version could be swapped, a requirements file with hashes would break, or worse, an attacker who gained access could swap a file under a trusted version. Fixing the name to one file keeps "version 2.3.1" meaning one thing.
The three cases
| Case | What happened | What to do |
|---|---|---|
| File exists | You are re-uploading the same filename | Increase the version |
| File deleted earlier | The slot is spent anyway | Increase the version |
| Same content under another name | PyPI rejects duplicates of content | Change the content, usually by bumping the version |
Steps to recover from a bad upload
- Do not try to delete and re-upload. It will fail again.
- Fix the problem in the code or the build.
- Increase the version, for example from 2.3.1 to 2.3.2, or use a post or release candidate style version if that suits your scheme.
- Rebuild and upload both sdist and wheel for the new version.
- If the bad file was dangerous, tell users to avoid it and see whether the registry's yank option fits your case. See PyPI yanked releases and pinned installs.
- Rotate any secret that went into the bad build.
Prevent it
- Build once in CI and upload that exact output. A second build attempt at a later step is how mismatches happen.
- Use a test index for a dry run before the real upload.
- Make the version bump part of the release checklist, ideally automated from a tag.
- Check the built files before upload, for contents and secrets.
For the same property on other registries, read can you overwrite a published package version.
Safeguard's dependency scanning and SBOM generation work on the exact versions you release and consume, which is the identity PyPI makes permanent.
Quick check
Can I delete the file and upload it again?
No. PyPI does not allow a filename to be reused, even when the file no longer exists.
What is the quickest fix?
Increase the version number, rebuild, and upload the new files.
Sources
Last reviewed: 19 October 2026.
