TestPyPI and PyPI: metadata validation parity across the integration boundary

Short answer

TestPyPI and PyPI run the same Warehouse codebase, so core upload-time metadata validation — name normalization, PEP 440 version parsing, Metadata-Version checks, and trove classifier validation — is broadly identical. But parity is not guaranteed at any given moment, dependency resolution is definitively not consistent across the two instances, and there is no promotion mechanism: you must re-upload to PyPI, though you can reuse the exact same artifact files.

What is confirmed vs. likely

Confirmed by design: both instances are separate deployments of the same open-source Warehouse project with separate databases, accounts, and API tokens. There is no cross-instance transfer of projects, so "promotion" means uploading the same files again.

Likely but deployment-sensitive: because both run Warehouse, validation rules for uploads tend to match. However, TestPyPI may run a newer revision or different configuration, and PyPI-only policies (name reservation, prohibited names, project quotas, trusted publisher/OIDC setup) can reject what TestPyPI accepted. Treat TestPyPI success as a strong signal, not a guarantee.

Dependency resolution is the real parity gap

TestPyPI hosts only packages explicitly uploaded to it. If your package declares dependencies that exist only on PyPI, this fails:

pip install --index-url https://test.pypi.org/simple your-package

You must layer PyPI in as a fallback:

pip install --index-url https://test.pypi.org/simple \
  --extra-index-url https://pypi.org/simple \
  your-package

Note that mixing indexes can change resolution outcomes versus a pure-PyPI install, and it carries a dependency-confusion risk if a name exists on both indexes. For a production-fidelity check, compare against a dry run:

pip install --dry-run your-package==1.0.0

Recommended test-to-production workflow

1. Build once: python -m build
2. Upload to TestPyPI with a TestPyPI-scoped token: twine upload -r testpypi dist/*
3. Install from TestPyPI with PyPI as extra index and verify behavior.
4. Upload the identical files to PyPI: twine upload dist/*
5. Optionally confirm byte-identical promotion by comparing SHA256 hashes of the artifacts on both instances.

Because the same artifact is reused, all embedded metadata (classifiers, requires-dist, description) carries over unchanged — the re-upload does not alter it.

Caveats worth remembering

• TestPyPI periodically purges data; never treat it as durable storage.
• Version immutability is per-instance: a filename published on PyPI cannot be replaced, independent of anything you did on TestPyPI.
• Use separate API tokens per instance; never reuse production credentials on TestPyPI.
• If you suspect a specific validation discrepancy, test it directly: upload an artifact with a deliberately bad classifier or malformed version to TestPyPI and compare the rejection with PyPI's response, and check the Warehouse changelog for recent changes.

Bottom line: TestPyPI is a reliable rehearsal for upload validation and a poor replica of dependency resolution, and "promotion" is simply re-uploading the same built artifacts with separate credentials.