PyPI now supports archiving projects

Facundo Tuesca
research-practice

PyPI now supports marking projects as archived. Project owners can now archive their project to let users know that the project is not expected to receive any more updates.

Project archival is a single piece in a larger supply-chain security puzzle: by exposing archival statuses, PyPI enables downstream consumers to make more informed decisions about which packages they depend on. In particular, an archived project is a clear signal that a project intends to make no future security fixes or perform ongoing maintenance.

Thanks to this signal, downstream consumers can make better-informed decisions about whether to limit or migrate away from their use of a particular package without having to resort to heuristics around project activity or maintenance status. This results in a virtuous double-effect: downstreams are better informed about the status of their supply chain, and upstreams should receive fewer distracting, superfluous requests for maintenance information from upstreams.

This work is a continuation of our ongoing efforts to bring supply-chain security improvements to PyPI, as well as Python packaging more generally. For more information about our previous efforts, check out some of our earlier writeups:

Finally, project archival is just the beginning: we’re also looking into additional maintainer-controlled project statuses, as well as additional PyPI features to improve both upstream and downstream experiences when handling project “lifecycles.” Stay tuned for additional progress on those fronts!

Why statuses matter

The ability to mark the status of projects on PyPI has been a long-standing feature request. This is for projects that are abandoned, unmaintained, feature-complete, deprecated, etc., where the maintainer wants to correctly set expectations for users of the package about expected future updates and even endorsement of use.

An interesting problem that comes up then is: which statuses should be supported, and what are their semantics? Ideally, a project should have a single “main” status, but some of these statuses overlap semantically (like “abandoned” and “unmaintained”), while others are not mutually exclusive (a project can be both feature-complete and unmaintained).

There is an open discussion on PyPI’s issue tracker about what statuses should be added or not. As a first step, there was agreement that “archived” is useful and has clear enough semantics to be the first status added.

Archiving a project

Owners of a project can archive it by navigating to the project’s settings page and scrolling down near the end to the following section:

Figure 1: Archiving a project

This lets the owner know the semantics (no further updates expected), and recommends a way to give users more context via a final release.

After archiving the project, users will see the following notice in the project’s main PyPI page:

Figure 2: Project has been archived

Finally, the project owners can always unarchive a project if needed.

Importantly: project archival is not the same thing as yanking or outright deletion. An archived project is never deleted and, unlike projects that are yanked, can still be resolved by default. PyPI will also never delete or prune projects based on their archival status: archiving is intended solely to empower project maintainers to communicate their project’s status to downstream consumers.

Under the hood

Behind the scenes, maintainer-controlled project statuses are a specialization of a larger feature also recently added to PyPI: project quarantine. Thanks to the LifecycleStatus model and state machine developed for the quarantine feature, we were able to rapidly extend PyPI’s project statuses to include a new “archived” state. We expect future state additions to be similarly easy!

More information about project quarantine can be found on the PyPI blog.

Where do we go from here?

Project archivals are currently recorded and presented on PyPI’s web interface. This is great for humans making decisions about whether to use (or discontinue use of) a package, but doesn’t immediately help installers (like pip and uv) alert developers when their dependencies become archived.

In other words: this feature will help users but it doesn’t yet help the machine-readable case. That’s something we’re working on!

The “archived” state is also not the end-all, be-all of packaging statuses: as mentioned above, there are numerous other states (“deprecated,” “feature-complete,” etc.) that project maintainers want to express in a consistent fashion. Now that we have a blueprint for doing that with the “archived” state, we’ll be looking into those as well.

Acknowledgements

We would like to thank the PyPI administrators and maintainers for reviewing our work and offering us invaluable feedback throughout development. In particular, we thank Mike Fiedler (as PyPI’s Safety and Security Engineer) and Dustin Ingram (as one of PyPI’s maintainer-administrators) for their time and consideration.

Our development on this feature is part of our ongoing work on PyPI and Python packaging, as funded by Alpha-Omega. Alpha-Omega’s mission is to protect society by catalyzing sustainable security improvements to the most critical open-source software projects and ecosystems.