Using the PyDist CLI

The PyDist CLI lets you publish and install packages from PyDist with minimal configuration. Install it with pip install pydist-cli and then run pydist publish from the root directory of your package to publish it, or pydist install <package> to install a package.

You can set an API key using the environment variable PYDIST_API_KEY, the command-line flag --api-key, or by setting api_key in a .pydist.json file, either in the root of your project or your home folder. If you do not provide an API key, you will be prompted for one at runtime, which will be saved in a .pydist.json file.

Note that the CLI only supports Python 3.5 and higher.

Installing from PyDist

Instead of using the CLI, you can install packages through PyDist using standard python tools like pip and pipenv with a single configuration option.

For pip, use the --index-url option:

pip install --index-url https://[tag]:[API Key] [package_name]


pip install --index-url https://[tag]:[API Key] -r requirements.txt

Alternatively, you can configure pip with a pip.conf file in any of:

  • Your virtual environment directory (e.g. ./venv)
  • Your user config directory's pip subdirectory (~/.config/pip/ on Linux)
  • Your global config directory pip subdirectory (~/.config/pip/ on Linux)

Which directory you choose determines how broadly the configuration will apply—just within that virtual environment, for the user, or for the entire system. The pip.conf file should contain:

index-url = https://[tag]:[API Key]

On some platforms, pip does not respect the provided username/password and will prompt you for them on each command.


For poetry, add a [[tool.poetry.source]] section to your pyproject.toml file with:

name = 'pydist'
url = 'https://[tag]:[API Key]'


For pipenv, replace the [[source]] section at the top of Pipfile with:

url = 'https://[tag]:[API Key]'
verify_ssl = true
name = 'pydist'

Note that the URL includes a tag as a username, which can be anything, and your API Key as a password.

Uploading to PyDist

The process of uploading a package to PyDist is almost identical to uploading a package to PyPI.

Before you can upload a python package, you need to create one or more distributions of that package. Per Python's Packaging User Guide, you first want to make sure the packages setuptools and wheel are installed, then run python sdist bdist_wheel, which will build source and binary wheel distributions of your package in the dist/ directory.

Running python creates a build/ directory in addition to the dist/ directory. Subsequent builds will re-use the directory. If you delete a file from the package source and re-build, the resulting distributions will still include the file if it was in dist/. Thus it is safest to delete the build/ directory after building.

After building distributions in your dist/ directory, you can upload them using twine by running:

twine upload --repository-url dist/*

You will be prompted for a username and a password. The username can be blank; provide an API Key as a password. Alternatively, you can supply the flags --username "" and --password [API Key], or you can configure twine with a .pypirc file in your home directory. The file should look like:

index-servers =

username: [tag]
password: [API Key]

Then you only need to supply the name of the repository in your .pypirc to upload to:

twine upload --repository pydist dist/*

You should delete the dist/ directory afterwards to avoid re-uploading distributions after subsequent builds.


If you use poetry publish to upload your package, you will need to do some additional configuration:

poetry config repositories.pydist
poetry config http-basic.pydist [tag] [API Key]

You can then upload packages with poetry publish --repository pydist.

Your PyDist plan limits the number of distributions you upload. The above instructions will build and upload 2 distributions for each release.

You can find the packages you've uploading on the Packages tab.

Access Control

PyDist lets you create unlimited API keys with varying privileges, which allows you to distribute your code while maintaining strict access controls. You can create read-only API keys through the keys management interface. These can be used to distribute code to your servers while mitigating the risk of malicious package uploads in the event that the key is compromised, or to distribute code to third-parties.

You can further restrict read-only keys to a whitelist of specific packages you have uploaded. These keys can only be used to download those packages, or packages mirrored from PyPI.

Forking PyPI Packages

PyDist lets you switch from a PyPI package to an internal fork of that package without changing any code or requirements in your applications. Simply upload your fork to PyDist under the same name as the original package. Since your organization's packages always take precedence over PyPI packages by the same name, all of your applications will install the fork instead of the original package.

Even if you make no changes to the package code, forking allows you to upload additional distributions for each release. This can be useful if the package you would like to use does not offer binary wheels for the platform or python version your applications run on, but you would like to avoid having to build the packages from source every time you build your application.

You should increment the version number of the package before uploading your fork, so that your applications do not pick up the forked version until they upgrade dependencies. This is especially important if your applications verify package integrity, as your fork will have different hashes than the original package.

Infrastructure Insights

It is hard to keep perfect track of every package you install, especially as your dependencies introduce new dependencies of their own. The Insights tab gives you visibility, listing which packages you have installed. You can also see where they are installed, either by using a different API Key for each machine or service installing packages, or by using tags.

Tags are be added before the API Key in the PyDist index URL, e.g.

https://webserver:[API Key]