Chocolatey is a package manager for Windows (like apt-get but for Windows). Chocolatey is built on top of NuGet and PowerShell (the automation language for Windows). You can package and install anything on Windows using Chocolatey - if it can be automated, Chocolatey and PowerShell can install, upgrade, and uninstall it.
For more information on Chocolatey, please see:
- Chocolatey: The official website for Chocolatey
- Chocolatey Documentation: The official docs for Chocolatey
- Create a Chocolatey Package
- Install Chocolatey
- Build/Test/Push a Chocolatey Package
Chocolatey packages are known as nupkg files, which is a compiled NuSpec or a fancy zip file that knows about package metadata (including dependencies and versioning). These packages are an enhanced NuGet package, they have additional metadata that is specific to Chocolatey. Chocolatey is also compatible with vanilla NuGet packages. A Chocolatey package can contain embedded software and/or automation scripts. For more information on how Chocolatey works see: How Does Chocolatey Work
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:
|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|
Prerequisites to creating your Choco package.
Documentation on the Chocolatey CLI including a full list of commands can be found here.
The Chocolatey Windows package manager uses the same infrastructure as NuGet. Therefore packages are based on the same principles. One of those is a package description (specification) in xml format, known as the Nuspec file.
The following are the main elements of a Chocolatey package. Only the Nuspec is required (#1 below).
chocolateyInstall.ps1is triggered on install and upgrade.
- any application files to include (it is highly suggested that you are the author in this case or you have the right to distribute files). EXE files in the package/downloaded to package folder from
chocolateyInstall.ps1will get a link to the command line.
chocolateyUninstall.ps1, for uninstalling your package.
The endpoint for the chocolatey packages API is:
Open a command line in the directory where the nuspec is and type
This generates a nupkg (
.nupkg) file like
your-package-1.2.3.nupkg that you can upload.
To test the package you just built, open a command line shell and navigate to the directory where the *.nupkg file is located. Then type:
choco install packageName -dv -s .
You can upload your package using the Chocolatey CLI.
You can publish a nupkg file that you've generated from your project, using nuget.
It's important to highlight that the source must point to a nuget v2 Repository as chocolatey is not compatible with Nuget v3
Then you can publish your package using:
choco push PACKAGE_NAME-PACKAGE_VERSION.nupkg -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2 -ApiKey API-KEY
For full details of how to install and setup the Cloudsmith CLI, see Command-Line Interface .
The command to upload a Chocolately package via the Cloudsmith CLI is:
cloudsmith push nuget OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.nupkg
cloudsmith push nuget your-account/your-repo your-package-1.2.3.nupkg
Please see Upload a Package for details of how to upload via the Website UI.
As a shortcut, you can set up the source (upstream) ahead of time, using
choco source add -n example-repo -s https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2 -u "token" -p "TOKEN"
choco source add -n example-repo -s https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2 -u "USERNAME" -p "PASSWORD"
choco sources add -n example-repo -s https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2 -u "USERNAME" -p "API-KEY"
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
Then to install a package, you use
choco install PACKAGE_NAME -Source example-repo
See, NuGet Feed, for how to create chocolatey packages using Nuget or the cloudsmith CLI. Just remember your source should point to a v2 Nuget repository.
Updated over 1 year ago