How to use Chocolatey
There are a few rules that you have to follow before pushing packages to chocolatey.org:
Is your package unqualified for the Chocolatey feed, but you like to be able to install it through Chocolatey? Don't worry, you can always host your package for free on MyGet. See Hosting Chocolatey Packages on MyGet.
*.ps1files. If you don’t respect this rule, some characters are not displayed correctly in the Gallery on Chocolatey.org, because the Gallery assumes
*.nuspecfiles with a Byte Order Mark (BOM). A
BOMis neither required nor recommended for
UTF-8, because it can lead to several issues.
BOM. PowerShell is ignoring the standards and needs a
BOMin order to recognize scripts as
UTF-8. Otherwise it processes non
<?xml version="1.0" encoding="utf-8"?>.
Note: There is a lot of confusion in the world of character encodings: For example,
ANSI is an incorrect term for the internal Windows character encodings, e. g.
Windows-1252. But you should not use this encoding family anyway.
The main release of a product versions are usually sufficient. If there are also beta versions available and you would rather have that, then please create both the official release and the beta (and set the beta as a prerelease when pushing the item to chocolatey.org). Regular users of packages may want to use official releases only and not betas.
There are three main elements to a chocolatey package. Only the nuspec is required (#1 below).
Note: Please maintain compatibility with Posh v2. Not every OS we support is on Posh v2 (nor comes OOB with Posh v3+). It's best to work with the widest compatibility of systems out there.
There is a video showing the creation of a package: http://www.youtube.com/watch?v=Wt_unjS_SUo
The video is a bit outdated in showing the contents of the chocolateyInstall.ps1. Have a look at what the chocolateyInstall.ps1 looks like now:
$packageName = 'windirstat' $fileType = 'exe' $url = 'http://prdownloads.sourceforge.net/windirstat/windirstat1_1_2_setup.exe' $silentArgs = '/S' Install-ChocolateyPackage $packageName $fileType "$silentArgs" "$url"
If you think you got what it takes and just want to know the basic steps to get a package out, there is a special Quick Start Guide for you.
For reference - Nuspec Reference
Chocolatey Windows package manager uses the same infrastructure as NuGet , the
Visual Studio package manager by
Microsoft. Therefore packages are based on the same principals. One of those is a package description (specification) in
xml format, known as the
Nuspec contains basic information such as the version, license, maintainer, and package dependencies.
Note: If your package uses recently introduced functionality, you might want to include
chocolatey as a dependency with the version being the lowest version that has the introduced functionality. Otherwise the installation could fail for users with an older version of
You can indicate the
Chocolatey dependency like any other dependency. E.g.:
<dependencies> <dependency id="Chocolatey" version="0.9.8.21" /> </dependencies>
Logically, the version is based on the lowest compatible version. But if you don't know and used a lot of sorcery in your package, depend on the version of
Chocolatey that you succesfully tested your package on.
As the package maintainer, you decide where the packaged application is installed or extracted to. Depending on your type of application (see “What distinction does chocolatey make between an installable and a portable application?” at the bottom of the FAQ) there are a couple of suitable locations:
The path returned by the helper
Get-BinRoot can be used as the parent directory for the installation.
Get-BinRoot will return the value of the environment variable
%ChocolateyBinRoot%. If the value does not contain a drive reference, the system drive will be prepended. If the environment variable is not set, the default path (
C:\Chocolatey\bin) will be returned.
As an example, MinGW uses
%ChocolateyBinRoot%. If the environment variable is not set, MinGW installs to
C:\Chocolatey\bin\MinGW by default. If
%ChocolateyBinRoot% is set to "C:\Common\bin", MinGW installs to
%ChocolateyBinRoot% gives the chocolatey user a way of controlling where packages are installed. If you want to allow customizing the installation path, then this is currently the way to go.
The original creator probably had a reason for choosing a specific default installation path.
If you think, the user should be able to customize this path and you, the package maintainer, know how to pass a custom path on to the installer, then you should use
You can extract the application within the package directory itself (or even ship an extracted version with the package). This allows chocolatey to automatically find executables and put those on
No matter how you decide, you are advised to state the default installation directory in your package description. This prevents confusion about where the application will end up being installed.
If you allow customizing the installation path, then append instructions on how to do that, too.
You can make packages that depend on other packages just by adding those dependencies to the nuspec. Take a look at ferventcoder.chocolatey.utilities nuspec.
Do not use a folder named “content” in your package. NuGet attaches a special meaning to this folder and will not allow you to have dependencies on packages that have content folders without also having a content folder.
The title of your package (
<title> tag in the nuspec) should be the same as the name of the application. Follow the official spelling, use upper and lower case and don’t forget the spaces. Examples of correct package titles are: Google Chrome, CCleaner, PuTTY and FileZilla. The title will appear on the left side in the package list of the chocolatey gallery, followed by the version.
There are some guidelines in terms of the package id (
<id> tag in the nuspec):
adobereader. It is highly suggested to use the hyphen method when there are long package names, because that increases readability.
keepass-langfilesis a proper package id, because it adds the language files for the main application which in this case is KeePass. Another example is
libreoffice-helpfor the help pack for LibreOffice, the open source office suite.
These guidelines are already commonly applied on packages for all major Linux distributions, because they lead to a more consistent look of software repositories, easier to remember package id’s and less considerations about the naming for package creators.
Note that a lot of packages in the Chocolatey Gallery don’t follow these guidelines. The simple reason is that the affected packages were created before the introduction of these guidelines.
If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages – see Rob’s guidance on this: http://devlicio.us/blogs/rob_reynolds/archive/2012/02/25/chocolatey-guidance-on-packaging-apps-with-both-an-install-and-executable-zip-option.aspx
<description> of the package should contain a short text or at least a few words about the software for which the package is made. Here are a few things that should be respected:
<releaseNotes>are parsed as Markdown, so don’t insert line breaks in the middle of sentences. Remember to add empty lines to separate paragraphs and add an empty line before a list.
Versioning can be both simple and complicated. The best recommendation is to use the same versioning that the installable/portable application uses. With chocolatey you get four version segments. If the application only uses 1, 2 or 3 version segments, follow suit.
If the 4th segment is used, some folks like to drop the segment altogether and use that as only the package fix notation using one of the notations in the next section. There is no recommendations at this time.
If you need to fix the package for some reason, you can use the fourth number for a package fix notation. There are two recommended methods of package fix version notation:
Date Package Fix Version Notation is recommended because one can ascertain what it is immediately upon seeing it.
Package fix version notation is only acceptable in the fourth segment. Do not use any of the other segments for package fix notation. If an application only uses 1 or 2 version segments, add zeros into the other segments until you get to the 4th segment (i.e. 22.214.171.12420627).
When the fourth segment is used, it is recommended to add two zeroes (00) to the end of the version. Then when you need to fix, you just increment that number. So if the package was ruby and the version was 2.0.0-p353, the package is 126.96.36.199300 (adding the two zeroes at the end). Then a fix would be 188.8.131.52301 and so on.
For chocolatey, internationalization and localization of packages is very important, because it has users from all over the world. Many applications support multiple languages, but they use several different methods to achieve that. Therefore, there is no standard how internationalization/localization has to be integrated into packages. However, here are a few examples of packages that use various techniques. You can use them as inspiration for new packages:
packageid, then call it
packageid-langfiles. The language files package for KeePass is an example how this can be achieved.
If there is an icon which is suitable for your package, you can specify it in the
<iconUrl> tag in the nuspec. But there are a few things you should consider:
If you have executables in the package or brought into the package folder during powershell run and you want to exclude them you need to create an empty file named exactly like (case sensitive) the executable with
.ignore suffixed on the end in the same directory where the executable is or will be.
Example: In the case of
Bob.exe you would create a file named
Bob.exe.ignore and that file would not get a redirect batch link. The chocolatey package has an example of that. To further expand,
bob.exe.ignore would not work because it doesn't have the correct casing.
If you don't want to see a hanging window when you open an application from the command line that was set up with chocolatey, you want to create a file next to the executable that is named exactly the same (case sensitive) with
.gui suffixed on the end.
Example: In the case of
Bob.exe you would create a file named
Bob.exe.gui and that file would be set up as a GUI application so the window will call it and then move on without waiting for it to finish. Again,
bob.exe.gui would not work because it doesn't have the correct casing.
Open a command line in the directory where the nuspec is and type cpack. That's it.
To test the package you just built, with the command line still open (and in the current working directory in the same folder as the newly created
*.nupkg file) type:
choco install packageName -source %cd%
This will install the package right out of your source. As you find things you may need to fix, you will want to delete the particular package folder out of the %ChocolateyInstall%\lib folder.
If you are using a Semver dash in your package version (such as 1.0.0-beta), you will need to use the
-pre switch or else you will get Unable to find package errors from
choco install. You can also specify
-version 1.0.0-beta to try to install that exact version.
If your changes to an existing package are not being loaded, check for a cached version of the package in %LocalAppData%\NuGet\Cache.
%cd% points to the current directory. You can specify multiple directories separated by a semicolon;
nuspec specifies dependencies that are not in your source, you should add their paths to the source directory. E.g. in the case of Chocolatey itself:
<dependencies> <dependency id="Chocolatey" version="0.9.8.20" /> </dependencies>
You'll need to append the API path like so:
-source '"%cd%;http://chocolatey.org/api/v2/"' (note the apostrophe then the double quotes here).
You can also use the
-debug switch on
choco install to provide more information.
To push your package after you have built and tested it, you type
cpush packageName.nupkg where packageName.nupkg is the name of the nupkg that was built with a version number as part of the package name. You must have an api key for http://chocolatey.org/ set. You can do that with nuget.exe. You can install nuget.commandline so you can set this (notice it is on nuget.org and not on chocolatey.org - chocolatey installs packages from both sources!).
Take a look at cpush
You can also log into chocolatey.org and upload your package from there.
I'm so glad you asked. Take a look at this repository and follow the instructions: https://github.com/chocolatey/chocolateytemplates
Yes - AutomaticPackages