Python Repository

Cloudsmith provides public & private repositories for Python packages

Python is an awesome general-purpose programming language (we use it!). Cloudsmith is proud to support fully-featured registries for managing your own public and private python packages.

For more information on Python, please see:

• Python: The official website for Python
• PyPi: The Python Package Index

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Note

📘 The main examples in this docs use pip or the Cloudsmith CLI. If you use UV and wants to learn how to integrate it with Cloudsmith, jump to the UV Support section.

Upload a Package

To upload, you need to generate your package first. You can do this with:

python setup.py bdist_wheel --universal

This generates a wheel package file (.whl) like your-package-1.2.3.whl that you can upload.

Note

This assumes that you've created a setup.py file for your project. Please see the official PyPA packaging guide on how to create a setup.py for more information. There are also different types of distributions that you might be interested in, such as a source distribution, tarball distribution, etc.

Upload via native Python tooling

The endpoint for the native Python API is:

https://python.cloudsmith.io/OWNER/REPOSITORY/

In order to authenticate for native publishing, you'll need to create a .pypirc file (in your $HOME or project directory), with the following:

[distutils]
index-servers =
  pypi
  cloudsmith
[cloudsmith]
  repository: https://python.cloudsmith.io/OWNER/REPOSITORY/
  username: USERNAME
  password: API-KEY

You can then publish from your project directory using twine:

twine upload -r cloudsmith dist/PACKAGE_NAME-PACKAGE_VERSION.whl

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Python package via the Cloudsmith CLI is:

cloudsmith push python OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.whl

Example:

cloudsmith push python org/repo boto3-1.4.4.py2.p3-none-any.whl

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Download / Install a package

Setup

You have a choice of 2 methods to set up your Cloudsmith repository:

• Python set up via command line
• Python set up via Pip

Public Repositories

Set up via command line

Tell pip the location of your Cloudsmith repository using the the --index-url option.

pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://dl.cloudsmith.io/public/OWNER/REPOSITORY/python/simple/

Set up via Pip

Similar to set up via command-line, pip needs to be passed the --index-url configuration option. To do this add --index-url to the top of your requirements.txt (or similar) file:

--index-url https://dl.cloudsmith.io/public/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

Private Repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

Set up via command line

pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/python/simple/

pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://USERNAME:PASSWORD@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/

pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://USERNAME:API-KEY@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/

pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/

Set up via Pip

Similar to set up via command-line, pip needs to be passed the --index-url configuration option. To do this add --index-url to the top of your requirements.txt (or similar) file:

--index-url https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

--index-url https://USERNAME:PASSWORD@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

--index-url https://USERNAME:API-KEY@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

--index-url https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

Tip

Private Repository Credential Security

As private repositories require authentication in order to access the repository content, when specifying a private repository in a requirements.txt file please bear in mind that the URL will contain the credentials (especially important if the requirements.txt file is shared.)

You could choose to encrypt your requirements.txt file via something like git-crypt (if you're using git or GitHub, for example).

Removing Setup

If you no longer want to install packages from the repository, remove the --index-url line from your $HOME/.pip/pip.conf file.

Extra index url

When using pip to access your packages, there are two parameter options to ensure pip searches your repository - they are --index-url and --extra-index-url.

There is an important distinction to be made between these parameters, especially from a security perspective.

Specifying --index-url will override pip's default repository and only search the specified repository. This is the recommended approach from Cloudsmith. This improves your security posture as it reduces the risk of malicious public packages being installed in place of your own.

Dependency confusion

An attack known as dependency confusion: where an attacker can claim the package on the public repository in a way that will ensure it gets chosen over the private package.

If you still wish to access third-party repositories, like pypi.org, paid-for Cloudsmith plans include upstream proxying. This allows your repository to call out to other python repositories whenever a package cannot be found in your repository. See the Upstream Proxying section below.

If your Cloudsmith plan does not include upstream proxying and some of your dependencies live outside your Cloudsmith repository, then you can also also specify extra index urls to pip. This is done by specifying --extra-index-url. When pip is supplied with extra index urls, it has a list of repositories it searches for packages (the extra urls plus the index url). Note, this list is not ordered. All repositories are considered equal and pip will simply search for the best package match according to PEP 440. Using the --extra-index-url increases your exposure to dependency confusion attacks.

See pip install for more information.

Note

To search your Cloudsmith repository for packages use the --index-url Pip configuration argument. Using the --index-url configuration option will force pip to search only the Cloudsmith repository and will result in pip not being able to install public (PyPi) packages that your private package may depend on. This reduces your exposure to dependency confusion attacks.

UV Support

uv is quickly gaining traction as a Python package and project manager. It stands out for its ultra-fast dependency resolution, native lock-file support (which enables reproducible builds, as we'll discuss later), and a built-in publisher.

In the following sections, you'll learn how to install and publish your Python packages with uv in your private Cloudsmith repositories.

Project setup

Requirements

In case you don't have it yet, use pip to install uv and build.

pip install uv --upgrade
uv pip install build

Create project assets

Let's start defining a new pyproject.toml file for your project. Replace OWNER, REPOSITORY with your own Cloudsmith Workspace and Repository names:

[project]
name            = "sample-flask-app"
version         = "0.1.0"
requires-python = ">=3.10"
dependencies    = [
  "requests==2.32.3"
]

[[tool.uv.index]]
name = "cloudsmith"
url  = "https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/python/simple/"
# optional, but recommended for publish:
publish-url = "https://python.cloudsmith.io/python/OWNER/REPOSITORY/"

Then, define the next environmental variables for uv to perform basic HTTP Auth. Replace API-KEY with your user API Token:

# install / resolution
export UV_INDEX_CLOUDSMITH_USERNAME=token       # literal string
export UV_INDEX_CLOUDSMITH_PASSWORD=API-KEY

# optional: forbid fallback to PyPI
export UV_PIP_NO_INDEX=1

# publishing
export UV_PUBLISH_USERNAME=token
export UV_PUBLISH_PASSWORD=<API-KEY>

uv will use them to authenticate against your Cloudsmith repository. Now, execute the next command to fetch and install all the required dependencies in your active virtual environment:

# create a venv first:
uv venv && source .venv/bin/activate 
# install dependencies
uv pip install --system -r pyproject.toml

You'll find information about the dependencies being fetched:

This will result in all required packages being fetched directly from your Cloudsmith repository (please note that an upstream needs to be configured).

Once installed, just run the next command to build your wheel package and the source distribution (.tar.gz) file, including your Python "source code" and everything required to run it:

python -m build && ls dist/

Once those assets are ready, just publish both artifacts to Cloudsmith. Remember to specify your cloudsmith index as defined in the [[tool.uv.index.name]] field in your project definition:

uv publish --index cloudsmith dist/*

Browse to your Cloudsmith repository to find your new application packages.

Note

📘 This example explain how to run it in your local machine, but instructions can be adjusted to run this process within any of the existing CI/CD tooling you might use: GitHub Actions, GitLab CI, Jenkins, TeamCity, etc. In this case, the only requirement is that the uv environmental variables are exported first, so you can push your artifacts into the private Cloudsmith repository. You can find a sample GH Action workflow reproducing a similar workflow.

Reproducible builds via uv compile

A software compiling process is reproducible when it ensures that it will always output the same binary.

uv compile allows you to lock the exact versions so the environment can be reproduced in later builds. Without locking, the versions of dependencies could change over time, when using a different tool, or across platforms.

For example, to freeze the dependencies of the previous pyproject.toml project and generate a deterministic lock‑file, execute:

uv pip compile pyproject.toml -o requirements.lock

This will generate a requirements.lock file like the following:

Resolved 5 packages in 581ms
# This file was autogenerated by uv via the following command:
#    uv pip compile pyproject.toml -o requirements.lock
certifi==2025.6.15
    # via requests
charset-normalizer==3.4.2
    # via requests
idna==3.10
    # via requests
requests==2.32.3
    # via sample-flask-app (pyproject.toml)
urllib3==2.5.0
    # via requests

This file specifies the version for each of the packages used and the its source. Adding the uv dependency freezing capabilities to Cloudsmith Upstreams caching will allow you to guarantee that the software you distribute remain stable and reproducible.

Once you have the file, you just need to use it to install your project and guarantee all remains unchanged:

uv pip install --system --strict -r requirements.lock

To learn more about other dependency declaration formats supported, visit the official documentation.

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Configurable Proxying Caching.

Please see Upstream Proxying for more details.

Upstreams provide a way to blend multiple Python repositories into a single repository. This allows your single Cloudsmith repository to serve packages from multiple 'upstream' repositories (like PyPi.org, Artifactory, DevPi etc). Please note, blended upstreams can be a source of dependency confusion attacks.

Key Signing Support

Troubleshooting

Please see the Troubleshooting page for further help and information.