Does PyPI's warehouse enforce idempotency for POST upload retries?

PyPI warehouse idempotency for POST upload retries

PyPI warehouse does not enforce standardized idempotency for POST upload retries. When twine retries a failed upload the server may respond with code 200 OK overwriting the existing package or with code 409 Conflict if it detects a duplicate. The twine --skip-existing flag only suppresses re-upload when the warehouse returns a distinct already exists response it does not protect against retries that receive success codes. Consequently CI pipelines and automated deployment scripts that rely on default retry logic risk duplicate writes or unintended overwrites. The behavior also varies across PyPI mirror deployments and custom installations as no universal idempotency key or response contract is documented.

Confirmed facts

• Warehouse idempotency is not guaranteed duplicate payloads may be overwritten or rejected depending on server configuration.
• twine --skip-existing works only when the server returns a specific already exists metadata match it does not guard against retries that return 200 OK.
• Common HTTP response codes for duplicate upload attempts are 200 OK (overwrite) and 409 Conflict (duplicate detected) but other codes may appear in custom deployments.

Common warehouse behaviors

1. Network retries that receive 200 OK will result in a new package version or overwriting risking duplicate data if the client does not check the response.
2. Retries that receive 409 Conflict indicate the warehouse detected a duplicate but client retry logic may still proceed if it ignores the code.
3. Idempotency can be enforced client side by using unique filenames incrementing versions or checking existing packages before upload.

Verification steps

1. Inspect the HTTP response code and body after a retry upload to a test PyPI instance.
2. Compare the package metadata name version before and after retry to detect overwrites or duplicates.
3. Check the warehouse server version or configuration documentation for idempotency guarantees.

To tailor further please share the HTTP response code and body seen after a retry upload.