Seventy commits, 11,770 issues. The repository is not a codebase. It is the written procedure for every decision a PyPI administrator has to make about a person.
The queue
pypi/support holds ten files. Nine of them are Markdown or YAML. The tenth is a GitHub Actions workflow added in May 2026, and it is the first executable thing the repository has ever contained.
Against those ten files sit 11,770 issues: 961 open, 10,809 closed. The repository has 70 commits. That works out to roughly 168 issues for every commit, and the ratio is the point. Nothing here ships. The files exist so that a volunteer reading issue number 11,000 makes the same decision a volunteer made on issue number 300.
The PyPI Universe field guide introduced this repository as one of two in the organization that ship no code, and quoted the line that draws the boundary. Here it is again, because everything downstream follows from it:
“Any issue which relates to an individual user or project, or requires administrator or moderator intervention, should be opened here. … Any issue that affects how PyPI works for all users, or require code or configuration changes, should not be opened here.”
pypi/support → README.md
The README then does four more things the summary skipped, and each one is a routing rule.
It refuses to enumerate its own scope. Rather than list every accepted request type, it says “See this page for the exact list” and points at the template chooser. The forms are the specification. When a form is added or removed, the README needs no edit, and in practice gets none.
It sends bugs, feature requests and usability complaints to pypi/warehouse. That link was corrected in May 2024 to say pypi rather than pypa. Two other pointers in the repository were not corrected and still name the old organization, which is worth knowing before you trust a URL you find here.
It refuses to be the security channel. Vulnerability reports go to pypi.org/security/, and the README declines to restate the policy on the grounds that the hosted version is the current one. A public issue tracker is a poor place to disclose a vulnerability, and a stale copy of a security policy is a poor place to read one.
It gives you an escape hatch. Under “If you are unsure where to file your issue” the README tells you to open one anyway and it will be transferred as necessary. The link there still reads github.com/pypa/pypi-support, an old name GitHub redirects. The hatch matters more than the stale URL: a queue that punishes people for guessing wrong gets fewer correct filings, not more.
Everything else is triage vocabulary. The repository carries 21 labels, and most name a decision rather than a component: PEP 541, name squat, mass name squat, similar project name, prohibited project name, quarantine, limit request, account-recovery, unverified email, typo email, awaiting response, requires triaging. The list tells you what kinds of trouble arrive here.
Intake
Six issue forms live in .github/ISSUE_TEMPLATE/. They were plain Markdown templates until February 2021, when they were converted to GitHub issue forms: structured YAML with typed fields, required validations and enforced checkboxes. That conversion is the single most consequential change in the repository's history. A Markdown template is a suggestion. A form with validations: required: true will not let the issue be opened.
| File | Form name | Label applied |
|---|---|---|
access-issues.yml | Network Access Issues | network |
account-recovery.yml | Account Recovery | account-recovery |
limit-request-file.yml | Size Limit Request (per-file) | limit request |
limit-request-project.yml | Size Limit Request (project-wide) | limit request |
mass-name-squatter.yml | Mass name squatting by user | mass name squat |
pep541-request.yml | Name retention related request (PEP 541) | PEP 541 |
Each form applies exactly one label. That is not decoration. The workflow in section seven depends on it, and so does every saved search a volunteer uses to work the queue.
access-issues.yml is the longest file in the repository and reads like a diagnostic script written for someone who has never run one. It opens with two admonitions: check status.python.org first, including past incidents, and understand that this form covers pypi.org, test.pypi.org and files.pythonhosted.org only, not python.org or docs.python.org. Those two paragraphs deflect a large share of what would otherwise arrive.
Then it asks for evidence, field by field, with the commands pre-typed inside fenced code blocks so the reporter only has to paste output. Required: platform details, dig for A and AAAA records on both hostnames, IPv4 traceroutes, IPv4 curl -vvv against a JSON endpoint and against one specific pinned file, and IPv4 openssl s_client. Optional: every IPv6 equivalent, on the grounds that not everyone has it.
One field is optional for a different reason. The fastly-debug.com blob is the most useful single artifact for diagnosing a CDN problem, and the form says so, then immediately warns that “this output is optional, as it encodes identifying information about your browser, public IP, and location.” It also warns that ad blockers will break the page. A form that tells you what it is about to collect, and lets you decline, is doing something most support intake does not.
account-recovery.yml is short: username, reason, and two mandatory checkboxes. The first makes you assert that you never generated or have lost the eight recovery codes that PyPI issues when two-factor authentication is enabled. That single checkbox closes the largest category of recovery request, because the honest answer is often that the codes exist in a password manager.
The second is labelled Acknowledgement, and its description is the most candid sentence in the repository: “By their nature account recovery issues are labor intensive. The PyPI team has limited resources available for their completion. There may be a delay of a week or more between responses for these issues.” You cannot open the issue without ticking “I understand that it may take a significant amount of time to process my account recovery request.”
Both size-limit forms carry a required checkbox reading “Does this project already exist?” The per-file form is blunt about it: “This project MUST EXIST for an increased limit to be set. An empty 0.0.0 release may be uploaded, if the project doesn't exist. You can delete this release immediately after uploading it.”
The requirement looks backwards until you remember where the limit lives. A file-size limit is a column on a project row in Warehouse's database. There is no place to record a limit for a project that has not been created, so the administrator cannot grant the request. The instruction to upload an empty 0.0.0 and then delete it is the workaround for a data model, published as user-facing policy.
Both forms also carry a checkbox that only exists because GitHub cannot do it for you: “I have updated the title.” The templates ship with placeholder titles (File Limit Request: PROJECT_NAME - 000 MiB and Project Limit Request: PROJECT_NAME - 00 GiB) and the queue is worked from the issue list, so an unedited title is a ticket nobody can triage without opening. Four of the six forms ask the reporter to rewrite the title by hand: the two limit forms enforce it with this checkbox, and mass-name-squatter.yml and pep541-request.yml ask for the same edit in prose.
There is a comment in both files worth stealing. The checkbox label is written as "Yes" in quotes, with the note: # should be a str but YAML parses unwrapped yes/no as bool. Someone hit that and left a sign.
The name-retention form does not ask what you want. It asks for the material a moderator will need in order to apply PEP 541, and its fields line up with the PEP's criteria one for one. Project URL and your PyPI username, both as required inputs. Reasons, phrased carefully as “Do you believe the project has been abandoned.” A dropdown that forces the request into one of two categories, Maintenance or Replacement, because the PEP applies different tests to each. Source repository URLs for both the current project and the one you intend to publish in its place, which is how you demonstrate the improvements the PEP requires. And a required field for contact attempts and research, with a clause that quietly limits what your evidence buys you: “Note moderators are obliged to contact owners independently.”
Your failed contact attempts are a precondition, not a substitute for the process. The moderators run their own.
One line in config.yml does most of the work: blank_issues_enabled: false. There is no way to open an untyped issue. Every arrival is one of six shapes, carries one label, and has already answered the questions the answer depends on.
The rest of the file is a routing table of six contact links, shown above the template list and leading away from the repository:
| Link | Goes to |
|---|---|
| Python Infrastructure Status Page | status.python.org, before reporting an outage |
| Organizations Feature Support | docs.pypi.org/organization-accounts/support/#organization-features |
| Organizations Billing Support | …/#organization-billing, for billing and type changes |
| Feature Request, UX issue or bug? | Warehouse's issue chooser |
| Security Policy | pypi.org/security/ |
| PSF Code of Conduct | pypa/.github → CODE_OF_CONDUCT.md |
A seventh form used to exist. organizations.yml was added in May 2023 and deleted on 2 April 2025 by a commit titled “redirect orgs to support inbox.” Organization support moved off the public tracker and onto a private inbox, which is the correct call for a channel that carries billing details. The same day brought a second commit, “mailto links not allowed,” which is why the two Organizations entries point at documentation pages rather than at an address. GitHub will not accept a mailto: URL in a contact link, so the replacement route goes through docs.
Policy one
PyPI ships two default ceilings: 100 MiB for a single file, and 10 GiB for a project's total footprint. Both are stated in the descriptions of the two limit forms. Raising either is a human decision, and the README is the only written record of how that decision is made.
It opens with the position, not the procedure: “Generally, projects should try to minimize the size of their distributions as much as possible. Large distributions consume significant amounts of PyPI's resources, and also generally do not provide a good user experience.” Then three lists, quoted here in full because a volunteer quotes them back verbatim.
Small increases, up to 200 MiB, are generally granted when:
Large increases, more than 200 MiB, are generally granted when:
Increases are generally denied when:
Read the lists against each other and the shape becomes clear. The same artifact appears on both sides, separated only by size: a small pre-trained model is granted, a large one is denied; a small JAR is granted, a large one is denied. The word doing the work is the adjective. 200 MiB is the hinge, and above it the burden shifts from “what is in the file” to “who are you,” which is why the only two large-grant reasons are hardware coverage and an established project or organization behind the name.
Two denial criteria are about behaviour rather than content. Frequent releases are denied because the cost is the product of size and cadence, not size alone: a 300 MiB nightly is 9 GB a month of storage and mirror traffic. Shipping another language's runtime is denied because the request is really a request to use PyPI as a general artifact store.
Now look back at the forms and the mapping is exact. Every criterion in the README has a field that feeds it.
| Form field | Criterion it answers |
|---|---|
| About the project: “what the project is and how long it has been active” | Associated with an established project or organization |
| “If you have made efforts to reduce the size… mention it here” | Has not made a best-effort to reduce release size |
| “If you bundle other packages… if you bundle example data…” | Includes a runtime, a JAR, or bundled binaries |
| How large is each release? (project-wide form) | Which threshold applies, small or large |
| How frequently do you make a release? (project-wide form) | Makes nightly releases and/or is published frequently |
| Which indexes: PyPI, TestPyPI, or both | Where to apply the change, since the two indexes hold separate limits |
The project-wide form even supplies a model answer in its placeholder text, showing the level of detail expected: “~200 MiB total. 2 Linux wheels at ~60 MiB, due to bundled libxml binaries. 6 Windows/MacOS wheels at ~10 MiB. The source tarball at ~10 MiB.” The form is teaching the requester how to make a case that can be granted.
Checkpoint 1 · the queue and its forms
Policy two
PEP 541, “Package Index Name Retention,” was written by Łukasz Langa in January 2017 and resolved in March 2018. It is a Process PEP, and it went through an approval path no other packaging PEP uses: the BDFL-Delegate recommended it to the PSF's Packaging Working Group, which voted on it after consulting the PSF's General Counsel. Amendments take the same route. The PEP says why in one sentence: the policy has potential legal ramifications for the Python Software Foundation.
Its premise is that a flat namespace makes a name a finite resource, and that as the index ages, collisions between the current use of a name and a proposed use become constant. Everything else is a set of tests.
The PEP puts the burden on the owner: “The user of the Package Index is solely responsible for being reachable by the Package Index maintainers for matters concerning projects that the user owns.” Maintainers must try at least three times, through three channels: the email on the user's PyPI profile, the address in the project's Author field, and any address found in the project's documentation on the index or on its listed home page. Then the sentence that starts every clock in the runbook: “The maintainers stop trying to reach the user after six weeks.”
A project is abandoned when all three hold: the owner is not reachable, there have been no releases in the past twelve months, and there is no activity from the owner on the project's home page (or no home page is listed). One line disposes of every other project on the index: “All other projects are considered active.”
Abandonment alone changes nothing. “Projects are never removed from the Package Index solely on the basis of abandonment. Artifacts uploaded to the Package Index hold inherent historical value.” What abandonment does is unlock two named procedures, with different bars.
To take over an abandoned project and keep maintaining it, all five must hold: the project is abandoned by the test above; the candidate demonstrates their own failed attempts to contact the owner; the candidate demonstrates improvements made on their own fork; the candidate demonstrates why a fork under a different name is not an acceptable workaround; and the index maintainers have no additional reservations. Then a sentence that ends most disputes on its own: “Under no circumstances will a name be reassigned against the wishes of a reachable owner.”
To take the name for a different project, the bar rises. The same five conditions apply, with “improvements on a fork” replaced by proof that the replacement project already exists and meets notability requirements, plus one more that no amount of arguing can supply: “download statistics on the Package Index for the existing package indicate project is not being used.”
The PEP declines the hardest cases outright. “The maintainers of the Package Index are not arbiters in disputes around active projects.” It then lists three real-world patterns and says none of them qualify: co-maintainers who part ways and both want the name; someone who owned the name off-index and found it taken on-index, “even if User A's project X gains notability and the User B's project X is not notable”; and a contributor whose fixes go unreleased, “even if User A agrees to publish a new version and later doesn't.” The recommendation is to get in touch and solve it by respectful communication.
That refusal is the load-bearing part of the document. It means the index is not a trademark registry and will not be used as one.
A separate list covers removal on sight: non-conformance with the Terms of Use, malware, spam, illegal content, violation of copyright, trademarks, patents or licenses, Code of Conduct violations, obfuscation used to hide functionality, and abuse of the index for purposes it was not intended for. Among them sits the definition that the runbook uses constantly: “project is name squatting (package has no functionality or is empty).”
Intellectual property is routed away from the queue entirely. The PSF and the index maintainers do not pre-screen uploads; possibly infringing packages go to legal@python.org, and counsel decides. A package may be removed or transferred “at the sole discretion of the Python Software Foundation to address a claim of infringement,” and in some cases before the owner responds.
Index maintainers escalate to the Packaging Workgroup when a matter is not clear enough. Code of Conduct violations and legal claims require judgement by the PSF Board, whose recommendations then go back to the Workgroup for review. The final sentence names the authority without hedging: “The Packaging Workgroup has the final say in any disputes covered by this document and can decide to reassign or remove a project from the Package Index after careful consideration even when not all requirements listed here are met.”
Note the last clause. The written criteria bind the process, not the outcome.
The runbook
PEP 541 tells you what must be true. It does not tell you what to do on a Tuesday with an issue in front of you. name-retention/README.md, added in April 2024, does. It is 215 lines: a Mermaid flowchart, four email templates, and seven canned GitHub comments.
It begins by naming its own limits, in two sentences placed above the diagram rather than buried at the end:
“This is incomplete and doesn't account for special cases. From anywhere in the flow, if the process feels wrong: move to Special case and consult with colleagues or PyPI admins.”
pypi/support → name-retention/README.md
The flowchart has a node called Special case with no incoming edges drawn, because every node is an incoming edge. A procedure that ships with a documented exit is a procedure people will follow, because it does not ask them to pretend it covers everything.
name-retention/README.md. Dashed edges are branches that leave the main path. Every terminal box is a recommendation; the decision belongs to the administrators. From any node, a volunteer may exit to Special case.The flow triages before it investigates, and each question is cheap to answer from the project page.
Requests sit long enough that the situation moves without them. If the transfer or deletion already happened, comment and stop.
No uploads means an empty name, which PEP 541 defines as squatting. That routes straight to the removal lane and never touches the abandonment test. A third answer exists, “no such project,” because people file against names that were never registered.
Uploads that do nothing are the other half of the PEP's squatting definition, “has no functionality or is empty.” Same lane. The asterisk in the source acknowledges this is a judgement call.
A working project that someone wants to continue enters the transfer lane. A working project that someone wants to replace gets a comment, not a lane. The canned reply quotes the PEP's own line about historical value and asks the question the criteria imply: why can you not use a different name?
Courtesy notice, wait, removal notice. The courtesy notice states the finding and offers the owner a way out: “If you would like to release a project under this name, please do so as soon as possible. Otherwise, we will recommend that the PyPI Administrators delete it in about a week.” If nothing changes, the removal notice goes out and a comment records that the name will become available.
The reachability email is the centre of the whole document. It goes to four addresses at once: $PYPI_USER_ADDRESS, $PROJECT_AUTHOR_ADDRESS, $UPLOADER_ADDRESS and $ADDRESS_FROM_DOCS. Those are PEP 541's three channels, expanded to four because the uploader and the account owner are not always the same person. The subject line is ACTION REQUIRED: PyPI $PROJECT name retention.
The body states the request, links the support issue, and then does something worth copying: it offers the owner the cheapest possible way to end the matter on their own terms.
If you would like to keep the project, please reply to this email.
If you are willing to give up the project, it would help us if you do it
yourself: go to https://pypi.org/manage/project/$PROJECT/collaboration/,
log in, and invite $CANDIDATE as an Owner.Three attempts, two weeks apart, with one paragraph of difference between them. The first adds nothing. The second says “This is our second attempt to reach you. We tried two weeks ago.” The third is the one that matters:
This is our third and final attempt to reach you. If you do not reply in
two weeks, we will recommend that the PyPI Administrators transfer
ownership of PROJECT to CANDIDATE.Three mails at two-week intervals plus a final two-week wait is the six weeks PEP 541 allows, spent evenly. All four templates close the same way: “Thank you for your time, PyPI Support.”
The templates use two notations. $VARIABLE marks a substitution. Braces with a pipe mark a choice the volunteer makes: {transferring ownership to them in order to continue maintaining it|to reuse the name for another project}, or {is empty|has no functionality}. One template covers both request types because the only difference is a clause.
Every initial GitHub comment carries the same paragraph, and it is the sentence that keeps the whole arrangement honest:
“Disclaimer: We are providing support to the PyPI Administrators to validate this request and make a recommendation on the outcome and actions to be taken. Final determination will be made by the PyPI Administrators when our process is complete.”
name-retention/README.md → Initial Response
Read the seven comment templates and four of them end in the words “we recommend”: the invalid-project removal, the reachable-owner close, the owner-requested transfer, and the abandoned-project transfer. Every action-oriented outcome is framed as a recommendation, never a decision. The other three don't need the word: the two intake templates end on the same final-determination disclaimer instead, and the different-name template ends by asking the requester a question. Volunteers gather evidence, run the clock and write a finding. They do not transfer anything. The one comment that closes a case rather than escalating it is “Owner is reachable,” which restates the PEP's hardest rule in two sentences: “$OWNER responded to our email, indicating that they want to keep the project. Projects are not transferred against the wishes of a reachable owner.”
The delta
PEP 541 is a policy document approved by a working group after legal review, so it is written to survive cases nobody has thought of yet. That makes it vague in exactly the places a volunteer needs a number. The runbook supplies the numbers without contradicting a line of it.
| Question | PEP 541 | The runbook |
|---|---|---|
| How many contact attempts? | “at least three times” | Exactly three, each a separate template with escalating language |
| How long between attempts? | Unspecified; “stop after six weeks” | Two weeks, three times, then a final two-week wait |
| Contact where? | Three channels, described | Four $ variables in one To: line, sent together |
| What does the mail say? | Nothing | Subject line, body, three escalation paragraphs, common closing |
| Squatting: how long to fix it? | Nothing. Squatting is simply “invalid” | Courtesy notice, then “about a week” |
| Reachable owner says no? | “Under no circumstances… against the wishes of a reachable owner” | A canned comment recommending the issue be closed |
| Replacement request on a working project? | Five criteria including notability and download statistics | One comment quoting the PEP and asking why a different name will not do |
| Who decides? | Packaging Workgroup has final say; maintainers escalate | PyPI Administrators, named in a disclaimer on every first reply |
| What if the process is wrong? | Workgroup may act “even when not all requirements… are met” | Exit to Special case from any node, consult colleagues or admins |
The last row is the pair to study. Both documents build the same escape, from opposite ends. The PEP grants the Workgroup power to act outside the written criteria. The runbook grants the volunteer permission to stop following it. Neither pretends the rules are complete.
One row is a genuine gap rather than a refinement. PEP 541 names the Packaging Workgroup as the final authority; the runbook names the PyPI Administrators. Those are not the same body, and neither document explains the relationship between them: no source here establishes an appeal procedure, or says which body defers to which. A reader who has only the runbook will not learn how that's resolved, and neither will this guide pretend to know.
Checkpoint 2 · the PEP and the runbook
The exception
The “no code” description of this repository was accurate until 7 May 2026, when a commit titled “feat: support autoresponder” added .github/workflows/response-time-comment.yml. Two follow-up commits on 13 and 15 May tightened its filtering and collapsed its API calls. It is 137 lines, and it is the only executable file pypi/support has.
It fires on issues: [opened], skips issues opened by bots or by anyone whose author_association is OWNER, MEMBER or COLLABORATOR, reads the issue's single label, counts how many open issues with that label are waiting ahead of it, and posts one comment.
The count is the interesting part. An issue is not counted as ahead of you if it is already on a project board, or if any non-bot member has commented on it. What remains is the number of issues in your category that nobody has touched. The query runs as one paginated GraphQL search that pulls project items and the first hundred comments for each candidate in the same request, replacing what the first version did in two REST calls per issue.
Then it says this, to every person who opens an issue:
“PyPI support is one paid staffer, plus volunteers, plus whatever part-time hours other PSF staff have to give. Often that's zero. If you'd like to help fund more staffing, the PSF takes donations at python.org/psf/donations. Either way, someone will get to your request eventually.”
.github/workflows/response-time-comment.yml
Every policy document above becomes legible once you read that sentence. The forms are long because the reviewer's time is the scarce resource. The runbook exists because the reviewer will not be the same person twice. The disclaimer exists because volunteers are not administrators. The queue design is a staffing constraint written down.
A workflow triggered by issues: opened in a public repository handles attacker-controlled input by definition. Anyone can open an issue, and the title and body are theirs to write. This file is careful in ways that are cheap to copy.
permissions: {} at workflow level and grants issues: write on the single job, with a trailing comment naming the one API call that needs it. The token cannot read code, write packages, or touch pull requests.actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3, with # v9.0.0 as a comment for humans. A tag can be moved; a SHA cannot.github-script, and issue fields are read as JS properties (issue.labels, issue.created_at) rather than interpolated into a run: block. Script injection through ${{ }} in a run: step is the standard way GitHub Actions workflows get compromised, and the file carries a comment saying so, with a link to the GitHub Security Lab writeup.github.event.issue.number, and the comment above it explains the choice: a server-generated integer, not user-controllable.try/catch, and a failure becomes core.warning. A broken autoresponder must not make an issue look like it failed to file.The comments are the unusual part. Most hardened workflows are hardened without saying why, which means the next editor removes the hardening by accident. This one explains each decision at the point where someone would undo it.
Checkpoint 3 · the autoresponder
The map
| Thing | Where | Why you'd look |
|---|---|---|
| What belongs in the queue | README.md |
The should and should-not lists, plus the pointer to Warehouse for bugs |
| The exact accepted request types | the template chooser | The forms are the specification; the README delegates to this page |
| Upload-limit criteria | README.md → “Guidelines for upload limit requests” |
Three lists and one 200 MiB hinge. The only written policy |
| Default limits | .github/ISSUE_TEMPLATE/limit-request-*.yml |
100 MiB per file, 10 GiB per project, stated in the form descriptions |
| Name-retention law | PEP 541 | Abandonment test, transfer criteria, the refusal to arbitrate, final authority |
| Name-retention procedure | name-retention/README.md |
Flowchart, four email templates, seven canned comments, all the timers |
| Where requests are routed away | .github/ISSUE_TEMPLATE/config.yml |
Six contact links: status page, Organizations, Warehouse, security, CoC |
| Security reports | pypi.org/security/ |
Never the issue tracker. The repository refuses to hold a copy |
| Infringement claims | legal@python.org |
PEP 541 routes these to PSF counsel, not to moderators |
| The autoresponder | .github/workflows/response-time-comment.yml |
Queue-depth logic, and a workflow-security example worth copying |
| Where this repository sits | The PyPI Universe field guide | The two process repositories, and the ten that hold the code |
Five things learned from reading the queue rather than the code.
Pyramid terms, plain English
__acl__config.scan()@view_config and registers whatever it finds. Without a scan, a decorator alone does nothing.Configurator object (via add_directive), so a plugin can offer its own verb, like config.add_periodic_task(...), instead of every caller repeating the same boilerplate.find_service()includeme(config)config.include("some.package") calls it and hands over the Configurator, so the plugin can register its own routes, views, and services.request_method="POST", that Pyramid checks before it will match that route or view to an incoming request.register_service_factory()find_service(): tells the registry "when someone asks for this interface, call this factory to build the answer."__getitem__ calls from the root. The traversal equivalent of a URL path segment.__getitem__, and whatever object you land on becomes the view's context.config.scan() actually uses. A decorator like @view_config just leaves a note for venusian to find later; it does nothing by itself until scanned.