Cloudsmith Documentation Hub

Welcome to the Cloudsmith Documentation Hub. You'll find comprehensive guides and documentation to help you start working with Cloudsmith as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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 n' paste snippets (with your namespace/repo pre-configured).

In the following examples:

Identifier

Description

OWNER

Your Cloudsmith account name or organisation name (namespace)

REPOSITORY

Your Cloudsmith Repository name (also called "slug")

TOKEN

Your Cloudsmith Entitlement Token (see Entitlements for more details)

USERNAME

Your Cloudsmith username

PASSWORD

Your Cloudsmith password

API-KEY

Your Cloudsmith API Key

PACKAGE_NAME

The name of your package

PACKAGE_VERSION

The version number of your package

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.

πŸ“˜

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 Website

Please see Upload a Package for details of how to upload via the Website UI.


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

Pip parameters

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

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

Specifying --index-url will override pip's default repository and only search the specified repository. This improves your security as it reduces the risk of malicious public packages being installed in place of your own. If you wish to have a fallback option, should a dependency not be part of your repository, you can pass this using --extra-index-url as outlined below.

Specifying --extra-index-url ensures that pip will have a backup repository should it not find all the required packages within the default repository (or the override specified by --index-url). It will fallback to this repository for the missing packages a backup.

At Cloudsmith, we want to ensure that the security of your packages as best as we can - it is for this reason that we recommend you specify all repositories using --index-url. This reduces the risk that a malicious package, with the same name yours, is uploaded to PyPi, which will be the first repository checked by pip unless this parameter is passed.

Should you wish for pip to fallback to the default repository, you can then pass the parameter --extra-index-url https://pypi.org/simple - see the links above for more information.

Public Repositories

Set up via command line

For the demonstrations below, we have opted to install packages directly using the the --index-url option when executing a pip command, you can also use --extra-index-url, however, this brings additional risk - see Pip parameters section for more information.

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 Cloudsmith repositories require authentication. You can choose between two types of authentication:

  • Entitlement Token Authentication
  • HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

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:[email protected]/basic/OWNER/REPOSITORY/python/simple/
pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/python/simple/
pip install PACKAGE_NAME==PACKAGE_VERSION --index-url https://token:[email protected]/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:[email protected]/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION
--index-url https://USERNAME:[email protected]/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION
--index-url https://token:[email protected]/basic/OWNER/REPOSITORY/python/simple/
PACKAGE_NAME==PACKAGE_VERSION

πŸ“˜

To search only 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.

To fallback to PyPi for public packages you will also need to pass the parameter:
--extra-index-url https://pypi.org/simple

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.


Upstream Proxying / Caching

Fixed Proxy
Cloudsmith currently supports fixed proxying to pypi.org. Proxied dependencies cannot currently be cached.

Please see Upstream Proxying for more details.

Key Signing Support

GPG

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated 11 days ago


Python Repository


Cloudsmith provides public & private repositories for Python packages

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Cloudsmith is the new standard in Package Management and Software Distribution

With support for all major package formats, you can trust us to manage your software supply chain.


Start My Free Trial Now
Cookie Declaration (Manage Cookies)