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, and projects like hatch that use it under the hood. 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>