The .pypirc
file#
A .pypirc
file allows you to define the configuration for package
indexes (referred to here as “repositories”), so that you don’t
have to enter the URL, username, or password whenever you upload a package with
twine or flit.
The format (originally defined by the distutils package) is:
[distutils]
index-servers =
first-repository
second-repository
[first-repository]
repository = <first-repository URL>
username = <first-repository username>
password = <first-repository password>
[second-repository]
repository = <second-repository URL>
username = <second-repository username>
password = <second-repository password>
The distutils
section defines an index-servers
field that lists the
name of all sections describing a repository.
Each section describing a repository defines three fields:
repository
: The URL of the repository.username
: The registered username on the repository.password
: The password that will used to authenticate the username.
Warning
Be aware that this stores your password in plain text. For better security, consider an alternative like keyring, setting environment variables, or providing the password on the command line.
Otherwise, set the permissions on .pypirc
so that only you can view
or modify it. For example, on Linux or macOS, run:
chmod 600 ~/.pypirc
Common configurations#
Note
These examples apply to twine. Other projects (e.g. flit) also use
.pypirc
, but with different defaults. Please refer to each project’s
documentation for more details and usage instructions.
Twine’s default configuration mimics a .pypirc
with repository sections
for PyPI and TestPyPI:
[distutils]
index-servers =
pypi
testpypi
[pypi]
repository = https://upload.pypi.org/legacy/
[testpypi]
repository = https://test.pypi.org/legacy/
Twine will add additional configuration from $HOME/.pypirc
, the command
line, and environment variables to this default configuration.
Using a PyPI token#
To set your API token for PyPI, you can create a $HOME/.pypirc
similar to:
[pypi]
username = __token__
password = <PyPI token>
For TestPyPI, add a [testpypi]
section, using the
API token from your TestPyPI account.
Using another package index#
To configure an additional repository, you’ll need to redefine the
index-servers
field to include the repository name. Here is a complete
example of a $HOME/.pypirc
for PyPI, TestPyPI, and a private repository:
[distutils]
index-servers =
pypi
testpypi
private-repository
[pypi]
username = __token__
password = <PyPI token>
[testpypi]
username = __token__
password = <TestPyPI token>
[private-repository]
repository = <private-repository URL>
username = <private-repository username>
password = <private-repository password>
Warning
Instead of using the password
field, consider saving your API tokens
and passwords securely using keyring (which is installed by Twine):
keyring set https://upload.pypi.org/legacy/ __token__
keyring set https://test.pypi.org/legacy/ __token__
keyring set <private-repository URL> <private-repository username>