How to install private python packages

Warning

This guide is for About Read the Docs for Business.

Read the Docs uses pip to install your Python packages. If you have private dependencies, you can install them from a private Git repository or a private repository manager.

From a Git repository

Pip supports installing packages from a Git repository using the URI form:

git+https://gitprovider.com/user/project.git@{version}

Or if your repository is private:

git+https://{token}@gitprovider.com/user/project.git@{version}

Where version can be a tag, a branch, or a commit. And token is a personal access token with read only permissions from your provider.

To install the package, you need to add the URI in your requirements file. Pip will automatically expand environment variables in your URI, so you don’t have to hard code the token in the URI. See using environment variables in Read the Docs for more information.

Note

You have to use the POSIX format for variable names (only uppercase letters and _ are allowed), and including a dollar sign and curly brackets around the name (${API_TOKEN}) for pip to be able to recognize them.

Below you can find how to get a personal access token from our supported providers. We will be using environment variables for the token.

GitHub

You need to create a personal access token with the repo scope. Check the GitHub documentation on how to create a personal token.

URI example:

git+https://${GITHUB_USER}:${GITHUB_TOKEN}@github.com/user/project.git@{version}

Warning

GitHub doesn’t support tokens per repository. A personal token will grant read and write access to all repositories the user has access to. You can create a machine user to give read access only to the repositories you need.

GitLab

You need to create a deploy token with the read_repository scope for the repository you want to install the package from. Check the GitLab documentation on how to create a deploy token.

URI example:

git+https://${GITLAB_TOKEN_USER}:${GITLAB_TOKEN}@gitlab.com/user/project.git@{version}

Here GITLAB_TOKEN_USER is the user from the deploy token you created, not your GitLab user.

Bitbucket

You need to create an app password with Read repositories permissions. Check the Bitbucket documentation on how to create an app password.

URI example:

git+https://${BITBUCKET_USER}:${BITBUCKET_APP_PASSWORD}@bitbucket.org/user/project.git@{version}'

Here BITBUCKET_USER is your Bitbucket user.

Warning

Bitbucket doesn’t support app passwords per repository. An app password will grant read access to all repositories the user has access to.

From a repository manager other than PyPI

Pip by default will install your packages from PyPI. If you are using a repository manager like pypiserver, or Nexus Repository, you need to set the --index-url option. You have two ways of set that option:

Set the PIP_INDEX_URL environment variable in Read the Docs with the index URL. See https://pip.pypa.io/en/stable/reference/requirements-file-format#using-environment-variables.
Put --index-url=https://my-index-url.com/ at the top of your requirements file. See Requirements File Format.

Note

Check your repository manager’s documentation to obtain the appropriate index URL.