Skip to content

Instantly share code, notes, and snippets.

Last active August 20, 2017 07:48
What would you like to do?
Chocolatey v0.10.8 Packaging
1. Determine Package Use:
Organization? Internal Use? - You are not subject to distribution
rights when you keep everything internal. Put the binaries directly
into the tools directory (as long as total nupkg size is under 1GB).
When bigger, look to use from a share or download binaries from an
internal location. Embedded binaries makes for the most reliable use
of Chocolatey. Use `$fileLocation` (`$file`/`$file64`) and
`Install-ChocolateyInstallPackage`/`Get-ChocolateyUnzip` in
You can also choose to download from internal urls, see the next
section, but ignore whether you have distribution rights or not, it
doesn't apply. Under no circumstances should download from the
internet, it is completely unreliable. See
to understand the limitations of a publicly available repository.
Community Repository?
Have Distribution Rights?
If you are the software vendor OR the software EXPLICITLY allows
redistribution and the total nupkg size will be under 200MB, you
have the option to embed the binaries directly into the package to
provide the most reliable install experience. Put the binaries
directly into the tools folder, use `$fileLocation` (`$file`/
`$file64`) and `Install-ChocolateyInstallPackage`/
`Get-ChocolateyUnzip` in tools\chocolateyInstall.ps1. Additionally,
fill out the LICENSE and VERIFICATION file (see 3 below and those
files for specifics).
NOTE: You can choose to download binaries at runtime, but be sure
the download location will remain stable. See the next section.
Do Not Have Distribution Rights?
- Note: Packages built this way cannot be 100% reliable, but it's a
constraint of publicly available packages and there is little
that can be done to change that. See
to better understand the limitations of a publicly available
Download Location is Publicly Available?
You will need to download the runtime files from their official
location at runtime. Use `$url`/`$url64` and
`Install-ChocolateyPackage`/`Install-ChocolateyZipPackage` in
Download Location is Not Publicly Available?
Stop here, you can't push this to the community repository. You
can ask the vendor for permission to embed, then include a PDF of
that signed permission directly in the package. Otherwise you
will need to seek alternate locations to non-publicly host the
Download Location Is Same For All Versions?
You still need to point to those urls, but you may wish to set up
something like Automatic Updater (AU) so that when a new version
of the software becomes available, the new package version
automatically gets pushed up to the community repository. See
2. Determine Package Type:
- Installer Package - contains an installer (everything in template is
geared towards this type of package)
- Zip Package - downloads or embeds and unpacks archives, may unpack
and run an installer using `Install-ChocolateyInstallPackage` as a
secondary step.
- Portable Package - Contains runtime binaries (or unpacks them as a
zip package) - cannot require administrative permissions to install
or use
- Config Package - sets config like files, registry keys, etc
- Extension Package - Packages that add PowerShell functions to
Chocolatey -
- Template Package - Packages that add templates like this for `choco
new -t=name` -
- Other - there are other types of packages as well, these are the main
package types seen in the wild
3. Fill out the package contents:
- tools\chocolateyBeforeModify.ps1 - remove if you have no processes
or services to shut down before upgrade/uninstall
- tools\LICENSE.txt / tools\VERIFICATION.txt - Remove if you are not
embedding binaries. Keep and fill out if you are embedding binaries
in the package AND pushing to the community repository, even if you
are the author of software. The file becomes easier to fill out
(does not require changes each version) if you are the software
vendor. If you building packages for internal use (organization,
etc), you don't need these files as you are not subject to
distribution rights internally.
- tools\chocolateyUninstall.ps1 - remove if autouninstaller can
automatically uninstall and you have nothing additional to do during
- Readme.txt - delete this file once you have read over and used
anything you've needed from here
- nuspec - fill this out, then clean out all the comments (you may wish
to leave the headers for the package vs software metadata)
- tools\chocolateyInstall.ps1 - instructions in next section.
4. ChocolateyInstall.ps1:
- For embedded binaries - use `$fileLocation` (`$file`/`$file64`) and
`Install-ChocolateyInstallPackage`/ `Get-ChocolateyUnzip`.
- Downloading binaries at runtime - use `$url`/`$url64` and
`Install-ChocolateyPackage` / `Install-ChocolateyZipPackage`.
- Other needs (creating files, setting registry keys), use regular
PowerShell to do so or see if there is a function already defined:
- There may also be functions available in extension packages, see for examples and
- Clean out the comments and sections you are not using.
5. Test the package to ensure install/uninstall work appropriately.
There is a test environment you can use for this -
6. Learn more about Chocolatey packaging - go through the workshop at
You will learn about
- General packaging
- Customizing package behavior at runtime (package parameters)
- Extension packages
- Custom packaging templates
- Setting up an internal Chocolatey.Server repository
- Adding and using internal repositories
- Reporting
- Advanced packaging templates when installers are not friendly to
7. Delete this file.
# IMPORTANT: Before releasing this package, copy/paste the next 2 lines into PowerShell to remove all comments from this file:
# $f='c:\path\to\thisFile.ps1'
# gc $f | ? {$_ -notmatch "^\s*#"} | % {$_ -replace '(^.*?)\s*?[^``]#.*','$1'} | Out-File $f+".~" -en utf8; mv -fo $f+".~" $f
# 1. See the _TODO.txt that is generated top level and read through that
# 2. Follow the documentation below to learn how to create a package for the package type you are creating.
# 3. In Chocolatey scripts, ALWAYS use absolute paths - $toolsDir gets you to the package's tools directory.
$ErrorActionPreference = 'Stop'; # stop on all errors
$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
# Internal packages (organizations) or software that has redistribution rights (community repo)
# - Use `Install-ChocolateyInstallPackage` instead of `Install-ChocolateyPackage`
# and put the binaries directly into the tools folder (we call it embedding)
#$fileLocation = Join-Path $toolsDir 'NAME_OF_EMBEDDED_INSTALLER_FILE'
# If embedding binaries increase total nupkg size to over 1GB, use share location or download from urls
# Community Repo: Use official urls for non-redist binaries or redist where total package size is over 200MB
# Internal/Organization: Download from internal location (internet sources are unreliable)
$url = '' # download url, HTTPS preferred
$url64 = '' # 64bit URL here (HTTPS preferred) or remove - if installer contains both (very rare), use $url
$packageArgs = @{
packageName = $env:ChocolateyPackageName
unzipLocation = $toolsDir
fileType = 'EXE_MSI_OR_MSU' #only one of these: exe, msi, msu
url = $url
url64bit = $url64
#file = $fileLocation
softwareName = 'bob*' #part or all of the Display Name as you see it in Programs and Features. It should be enough to be unique
# Checksums are now required as of 0.10.0.
# To determine checksums, you can get that from the original site if provided.
# You can also use checksum.exe (choco install checksum) and use it
# e.g. checksum -t sha256 -f path\to\file
checksum = ''
checksumType = 'sha256' #default is md5, can also be sha1, sha256 or sha512
checksum64 = ''
checksumType64= 'sha256' #default is checksumType
silentArgs = "/qn /norestart /l*v `"$($env:TEMP)\$($packageName).$($env:chocolateyPackageVersion).MsiInstall.log`"" # ALLUSERS=1 DISABLEDESKTOPSHORTCUT=1 ADDDESKTOPICON=0 ADDSTARTMENU=0
validExitCodes= @(0, 3010, 1641)
# Uncomment matching EXE type (sorted by most to least common)
#silentArgs = '/S' # NSIS
#silentArgs = '/s' # InstallShield
#silentArgs = '/s /v"/qn"' # InstallShield with MSI
#silentArgs = '/s' # Wise InstallMaster
#silentArgs = '-s' # Squirrel
#silentArgs = '-q' # Install4j
#silentArgs = '-s' # Ghost
# Note that some installers, in addition to the silentArgs above, may also need assistance of AHK to achieve silence.
#silentArgs = '' # none; make silent with input macro script like AutoHotKey (AHK)
#validExitCodes= @(0) #please insert other valid exit codes here
Install-ChocolateyPackage @packageArgs #
#Install-ChocolateyZipPackage @packageArgs #
## If you are making your own internal packages (organizations), you can embed the installer or
## put on internal file share and use the following instead (you'll need to add $file to the above)
#Install-ChocolateyInstallPackage @packageArgs #
## Main helper functions - these have error handling tucked into them already
## see
## Install an application, will assert administrative rights
## -
## -
## add additional optional arguments as necessary
##Install-ChocolateyPackage $packageName $fileType $silentArgs $url [$url64 -validExitCodes $validExitCodes -checksum $checksum -checksumType $checksumType -checksum64 $checksum64 -checksumType64 $checksumType64]
## Download and unpack a zip file -
##Install-ChocolateyZipPackage $packageName $url $toolsDir [$url64 -checksum $checksum -checksumType $checksumType -checksum64 $checksum64 -checksumType64 $checksumType64]
## Install Visual Studio Package -
#Install-ChocolateyVsixPackage $packageName $url [$vsVersion] [-checksum $checksum -checksumType $checksumType]
#Install-ChocolateyVsixPackage @packageArgs
## see the full list at
## downloader that the main helpers use to download items
## if removing $url64, please remove from here
## -
#Get-ChocolateyWebFile $packageName 'DOWNLOAD_TO_FILE_FULL_PATH' $url $url64
## Installer, will assert administrative rights - used by Install-ChocolateyPackage
## use this for embedding installers in the package when not going to community feed or when you have distribution rights
## -
#Install-ChocolateyInstallPackage $packageName $fileType $silentArgs '_FULLFILEPATH_' -validExitCodes $validExitCodes
## Unzips a file to the specified location - auto overwrites existing content
## -
#Get-ChocolateyUnzip "" $toolsDir
## Runs processes asserting UAC, will assert administrative rights - used by Install-ChocolateyInstallPackage
## -
#Start-ChocolateyProcessAsAdmin 'STATEMENTS_TO_RUN' 'Optional_Application_If_Not_PowerShell' -validExitCodes $validExitCodes
## To avoid quoting issues, you can also assemble your -Statements in another variable and pass it in
#$appPath = "$env:ProgramFiles\appname"
##Will resolve to C:\Program Files\appname
#$statementsToRun = "/C `"$appPath\bin\installservice.bat`""
#Start-ChocolateyProcessAsAdmin $statementsToRun cmd -validExitCodes $validExitCodes
## add specific folders to the path - any executables found in the chocolatey package
## folder will already be on the path. This is used in addition to that or for cases
## when a native installer doesn't add things to the path.
## -
#Install-ChocolateyPath 'LOCATION_TO_ADD_TO_PATH' 'User_OR_Machine' # Machine will assert administrative rights
## Add specific files as shortcuts to the desktop
## -
#$target = Join-Path $toolsDir "$($packageName).exe"
# Install-ChocolateyShortcut -shortcutFilePath "<path>" -targetPath "<path>" [-workDirectory "C:\" -arguments "C:\test.txt" -iconLocation "C:\test.ico" -description "This is the description"]
## Outputs the bitness of the OS (either "32" or "64")
## -
#$osBitness = Get-ProcessorBits
## Set persistent Environment variables
## -
#Install-ChocolateyEnvironmentVariable -variableName "SOMEVAR" -variableValue "value" [-variableType = 'Machine' #Defaults to 'User']
## Set up a file association
## -
## Adding a shim when not automatically found - Cocolatey automatically shims exe files found in package directory.
## -
## -
#$toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
# despite the name "Install-ChocolateyZipPackage" this also works with 7z archives
#Install-ChocolateyZipPackage $packageName $url $toolsDir $url64
#$binRoot = Get-BinRoot
#$installDir = Join-Path $binRoot "$packageName"
#Write-Host "Adding `'$installDir`' to the path and the current shell path"
#Install-ChocolateyPath "$installDir"
#$env:Path = "$($env:Path);$installDir"
# if removing $url64, please remove from here
# despite the name "Install-ChocolateyZipPackage" this also works with 7z archives
#Install-ChocolateyZipPackage "$packageName" "$url" "$installDir" "$url64"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment