PSA: proposed change to the `.pypirc` "spec"

woodruffw · January 7, 2026, 4:52pm

Hey packaging folks,

I’m opening this to raise awareness of a PPO change I proposed a few weeks ago, here:

github.com/pypa/packaging.python.org

pypirc: stipulate UTF-8 encoding

main ← ww/pypirc-utf8

opened 04:39AM - 25 Dec 25 UTC

woodruffw

+7 -0

This is a kind of interesting/nuanced thing, and I don't know if this PR is actu…ally the right approach 😅 -- I'm opening it for discussion! Context: `.pypirc` was never PEP'd; it was seemingly grandfathered in as a distutils implementation detail that gets respected by twine and flit (and perhaps others?). As a result, there's no stipulation as to what charset a `.pypirc` should be encoded with. In practice this is mostly a non-issue: most users will default to UTF-8, or in the worst case they'll use whatever system character encoding Python picks and _hopefully_ their consuming tool will too. However this does unfortunately break down sometimes, like with https://github.com/pypa/twine/pull/1268 recently. I think the best fix here is just to rip the bandaid off and stipulate that `.pypirc` files should be UTF-8, especially since upcoming Python versions will use UTF-8 in a blanket fashion by default. I've gone with "should" instead of "must" since twine _does_ make an effort to parse using the system charset, but this is a fallback we'd probably like to eventually remove. I'm not sure what flit does, but "should" also felt appropriate given that it's entirely open-ended at the moment 🙂 Open questions: * Can we just do this, without any additional standardization procedure? I think the answer is yes, since `.pypirc` is (1) kind of a legacy component anyways, and (2) never went through a packaging PEP (AFAICT). However, I'd like to hear if others feel otherwise. * Are there other publishing tools that use this file that this needs to be coordinated with? I know twine and flit for certain, and that uv doesn't (yet?) support it. Ref: https://github.com/astral-sh/uv/issues/7676 ---- 📚 Documentation preview 📚: https://python-packaging-user-guide--1980.org.readthedocs.build/en/1980/

TL;DR: .pypirc is the file format that twine (and others read) to access index configuration and credentials. It was never standardized by a PEP, so it’s one of the standards on PPO that sort of exists in a grandfathered state.

I’ve proposed a small change to the format, to stipulate that .pypirc SHOULD always be UTF-8 encoded, although tools MAY handle other encodings. This merely codifies the status quo, but it was implicit rather than explicit before.

I can’t imagine this would be a very controversial change, but I wanted to raise awareness here rather than merging it directly, since it exists in a weird gray area around pre-PyPA packaging standards. I welcome any thoughts/feedback!

(For background context, see the linked Twine PR in that PPO PR. The TL;DR is that some users end up with differently encoded .pypirc files through no fault of their own, and there’s no clear decision procedure for how Twine or other tools should handle that case.)