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    

Package Upload

Uploading to Cloudsmith is simple. We provide three ways to push your packages/files/assets into your repositories:

  • Upload via the package-specific native CLI / tools (where supported).
  • Upload via the API using tools/integrations (such as the official Cloudsmith CLI).
  • Upload directly via the website.

Upload via Native Tools

Documentation for package-specific native CLI and tooling is available on the website within each repository. For example, after selecting npm as the package format to upload, the following documentation is available:

Native CLI / API / Tools tabNative CLI / API / Tools tab

Native CLI / API / Tools tab

Upload via Cloudsmith CLI

To upload a package via the Cloudsmith CLI, use the cloudsmith push command:

cloudsmith push <format> OWNER/REPOSITORY <package_file>

For example:

cloudsmith push CLI examplecloudsmith push CLI example

cloudsmith push CLI example

Some formats may have additional parameters that need to specified (i.e distribution and version for Debian packages). Further format-specific examples of Cloudsmith CLI commands are available in the CLI documentation


Context-specific documentation, including copy and paste commands (with the owner/repository already configured) for the Cloudsmith CLI, is available within each repository on the Cloudsmith website.

You may also add optional tags to a package when uploading. For example, to upload a Debian package with optional tags, you add the --tags parameter to the push command:


Please see Package Tags for more information on package tagging

Upload via Website UI

We provide two ways to upload via the Website UI:

  • Via the repository packages list
  • Via the package upload page

Upload via Repository Packages list

Select the repository that you would like to upload into. The green "Upload" button has a dropdown list of the current package formats supported - clicking on one of these will pre-select the upload form type.

Upload drop-down listUpload drop-down list

Upload drop-down list

For this example, we will upload an npm package. If you select "npm" from the dropdown, the package upload form will look like this:

Package upload formPackage upload form

Package upload form


Uploading to a specific package format

Some formats require additional information for upload. For example, Debian requires the selection of a distribution and Maven requires a pom.xml or the entry of group-id, artifact-id and version.

Upload via Package Upload page

You can also access the Package Upload page by clicking the green "Upload" button (not the dropdown menu), and then selecting the package format you wish to upload from the formats tab:

Drop down for package format choiceDrop down for package format choice

Drop down for package format choice

When you have selected a package format from the Package Upload page; we provide tabs with additional information about the available upload methods:

  • Manually via the Website UI
  • Using the package-specific native tooling (where supported)
  • Using the Cloudsmith CLI
  • Using the Cloudsmith API
  • Using an Integration

If we select "npm", then the npm upload page will appear as follows:

Package upload pagePackage upload page

Package upload page

Clicking the green "Upload npm package" button in the Manually (Web UI) tab will then present the same package upload form as before.
We provide a drag-n-drop area to drag your file onto for upload. Click on the area to get the standard OS specific file selector. In my case; I have a demo folder with a single npm package in it:

Select it and the package will upload to the scratch space:

Package upload formPackage upload form

Package upload form

You need to click the green "Upload package" button to complete the upload process. Before you do that; you may need to add additional information, depending on the package format you are uploading.

Once you click the green "Upload npm package" button, the synchronisation process will begin.
After a few seconds your package will be available for download.

Frequently Asked Questions

Q. Is there a maximum file size for upload?

Yes, the current maximum file size is 5GB.

Q. While republishing a package with the same version via the Cloudsmith CLI, I get a message - "Republishing was not enabled for this package". Is there any way to "Allow Republishing" for packages ?

There are two ways to achieve this:

  1. When uploading you can add a --republish flag to the CLI command to enable republishing.

  2. You can also set it to be republish enabled by default for all uploads in the settings for your repository (configured via the Web UI - Settings > Replace Packages w/ Same Version):

Q. Is there a delay until a package is fully available? Our build pipeline publishes a new version of libraries each git commit and triggers changes on the git repository of the applications that are users of such library. Between the time frame of publishing and triggering a new build (that happens only after the publish has finished), we have some build failures. But on repetition they pass.

Processing for uploads happens asynchronously on Cloudsmith, so yes there's a small delay between pushing an artifact and it being available. Usually, this is around one minute, but can be longer if the system is under extreme load or if your account is uploading many artifacts in parallel.
There are a few options to consider to get around this today that are commonly utilised (and we're thinking of others):
(a) Add a wait (e.g. 1 minute) and retry mechanism to your jobs, to make them wait for the synchronisation; or
(b) Use the repository webhooks to ping your build system to continue after the package has synced; or
(c) Use the cloudsmith-cli (via cloudsmith push) to upload packages, since it has wait functionality built into it.

Q. If we are pushing from CI (multiple branches) - can the tags like "latest" be set to allow us to set the branch or is the expectation that we would encode the branch in the version? e.g. 1.0.0+bugfix

Tags are currently created by us automatically, and they wouldn't influence how a tool like pip can retrieve packages. So the way to go here would be to encode the information as Metadata into the version.

Updated 5 days ago

Package Upload

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)