Rob Reynolds edited this page Jan 5, 2017 · 128 revisions




How does choco work?

Creating Packages

How To's

Use Cases

Learning Resources


Clone this wiki locally


  • Windows 7+ / Windows Server 2003+
  • PowerShell v2+
  • .NET Framework 4+ (the installation will attempt to install .NET 4.0 if you do not have it installed)

That's it! All you need is choco.exe (that you get from the installation scripts) and you are good to go! No Visual Studio required.

Installing Chocolatey

Chocolatey installs in seconds. Just run the following command from an administrative PowerShell v3+ prompt (Ensure Get-ExecutionPolicy is not Restricted):

iwr -UseBasicParsing | iex

We take security very seriously. Learn more.

More Install Options

NOTE: Need to install a particular version of Chocolatey? Proxy? Install to a different location? Advanced Options? See Before You Install below. Alternative installation options? Non-Administrator installation? Restricted/no internet access on target machine? Looking for licensed edition installation?

To install chocolatey now, open an administrative command prompt and paste the text from the box below that applies to the name of your shell and press enter. If you need assistance opening an administrative prompt, see open an elevated prompt in Windows 8+ (or Windows 7).

NOTE: Please inspect prior to running any of these scripts to ensure safety. We already know it's safe, but you should also be comfortable before running any script from the internet you are not familiar with. All of these scripts download a remote PowerShell script and execute it on your machine.

NOTE: If your server is restricted to TLS 1.1+, you need to add additional logic to be able to download and install Chocolatey (this is not necessary when running Chocolatey normally as it does this automatically). If this is for organizational use, you should consider hosting the Chocolatey package internally and installing from there. Otherwise, please see the TLS1.1+ section

  • Cmd.exe -
@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString(''))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
iex ((New-Object System.Net.WebClient).DownloadString(''))
iwr -UseBasicParsing | iex

The easiest option to remember is this one. You may not need -UseBasicParsing.

What are these scripts doing? iwr (Invoke-WebRequest)/WebClient.DownloadString downloads the install script and passes it to iex (Invoke-Expression) to execute the contents of the script. This runs the installation script for Chocolatey.

Installing With Restricted TLS

If you see an error that looks similar to the following:

Exception calling "DownloadString" with "1" argument(s): "The underlying connection was closed: An unexpected error
occurred on a receive."
At line:1 char:1
+ iex ((New-Object System.Net.WebClient).DownloadString(' ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : WebException

It's possible that you are attempting to install from a server that needs to use TLS 1.1 or TLS 1.2 (has restricted the use of TLS 1.0 and SSL v3), you have some options.

Option 1

If you have the following:

  • PowerShell v3+
  • .NET Framework 4.5

You can just run the following instead of just the one-liner to get Chocolatey installed:

$securityProtocolSettingsOriginal = [System.Net.ServicePointManager]::SecurityProtocol

try {
  # Set TLS 1.2 (3072), then TLS 1.1 (768), then TLS 1.0 (192), finally SSL 3.0 (48)
  # Use integers because the enumeration values for TLS 1.2 and TLS 1.1 won't
  # exist in .NET 4.0, even though they are addressable if .NET 4.5+ is
  # installed (.NET 4.5 is an in-place upgrade).
  [System.Net.ServicePointManager]::SecurityProtocol = 3072 -bor 768 -bor 192 -bor 48
} catch {
  Write-Warning 'Unable to set PowerShell to use TLS 1.2 and TLS 1.1 due to old .NET Framework installed. If you see underlying connection closed or trust errors, you may need to do one or more of the following: (1) upgrade to .NET Framework 4.5 and PowerShell v3, (2) specify internal Chocolatey package location (set $env:chocolateyDownloadUrl prior to install or host the package internally), (3) use the Download + PowerShell method of install. See for all install options.'

iex ((New-Object System.Net.WebClient).DownloadString(''))

[System.Net.ServicePointManager]::SecurityProtocol = $securityProtocolSettingsOriginal

Option 2

You need to download and unzip the Chocolatey package, then call the PowerShell install script from there. See the Download + PowerShell Method section below.

Installing Behind a Proxy?

Have a proxy? Try

  • Cmd.exe -
@powershell -NoProfile -ExecutionPolicy Bypass -Command "[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials; iex ((New-Object System.Net.WebClient).DownloadString(''))" && SET PATH="%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
[System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials; iex ((New-Object System.Net.WebClient).DownloadString(''))

Explicit proxy?

See how to install behind an explicit proxy below.

Why does Chocolatey install where it does by default?

Great question - Why does Chocolatey install where it does

Before You Install

Can I install Chocolatey to another location?


  1. Create a machine level (user level will also work) environment variable named ChocolateyInstall and set it to the folder you want Chocolatey to install to prior to installation (this environment variable must be set globally or available to PowerShell- it is not enough to simply make it available to your current command prompt session).
  2. Don't use "C:\Chocolatey" unless necessary.
  3. Create the folder manually.
  4. If you have already installed (and want to change the location after the fact):
    • Follow the above steps.
    • Install Chocolatey again.
    • Copy/Move over the items from the old lib/bin directory.
    • Delete your old install directory.

NOTE: There is one really important consideration when installing Chocolatey to a non-default location - Chocolatey only locks down the permissions to Admins when installed to the default location. If you are installing to another location, you will need to handle this yourself. This is due to alternative locations could have a range of permissions that should not be changed - see for more details.

Can I install with a proxy?

You bet.

Chocolatey will detect and use a system set proxy. However some proxies will need to be set explicitly. To do so, you would do similar to Proxy settings for Chocolatey

Set the following environment variable(s) prior to install:

  • chocolateyProxyLocation - explicit proxy location. This includes the port.
  • chocolateyProxyUser / chocolateyProxyPassword - optional credentials for explicit proxy

In PowerShell, it looks like this:

$env:chocolateyProxyLocation = 'https://local/proxy/server'
#$env:chocolateyProxyUser = 'username'
#$env:chocolateyProxyPassword = 'password'
# install script

NOTE: This will only work with the installation methods that call as part of the install.

Can I install a particular version of Chocolatey?


Set the following environment variable prior to install:

  • chocolateyVersion - controls what version of Chocolatey is installed

In PowerShell, it looks like this:

$env:chocolateyVersion = ''
# install script

NOTE: This will only work with the installation methods that call as part of the install.

Can I use Windows built-in compression instead of downloading 7zip?


Set the following environment variable prior to install:

  • chocolateyUseWindowsCompression - this will bypass the download and use of 7zip.

In PowerShell, it looks like this:

$env:chocolateyUseWindowsCompression = 'true'
# install script

NOTE: This will only work with the installation methods that call as part of the install.

Non-Administrative Install

NOTE: This option should be a last resort and is considered to be an advanced scenario. Most things you do on Windows require administrative rights, especially surrounding software management, so you are going to be limited even in packages you attempt to install. If you run into issues with Chocolatey and you have set Chocolatey up this way, the first thing we are going to ask you to do is to see if it works when you have installed choco under normal circumstances. If you are using the community package repository, you should avoid this type of installation as over 75% of the packages you find there require administrative permission.

  1. You must choose a different location than the default (see before you install above). The default is a more secure location that only administrators can update.
  2. Follow that with the command line / PowerShell methods of installation.

Alternative Installation Options

There are a few ways to install Chocolatey. Chocolatey exists as a NuGet package, so virtually any way you can get a NuGet package, you have the opportunity to then install it.

Command Line

This really is the easiest method because it requires no configuration of PowerShell prior to executing it. Open a command line, paste the following and press <Enter>:

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "(iex ((new-object net.webclient).DownloadString(''))) >$null 2>&1" && SET PATH="%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"


This is the second-most easy method. Open a PowerShell command line and paste in the following and press <Enter>:

(iex ((new-object net.webclient).DownloadString('')))>$null 2>&1

Note: You must have your execution policy set to unrestricted (or at least in bypass) for this to work (Set-ExecutionPolicy Unrestricted). There have been reports that RemoteSigned is enough for the install to work. It downloads and runs (

Cmd/PowerShell w/Proxy Server

See Installing Chocolatey Behind a Proxy Server

PowerShell Through Batch Method

This is the best method if you want to repeat it or include it in source control. It requires no change to your existing PowerShell to allow for remote unsigned scripts.

Create a file named installChocolatey.cmd with the following:

@echo off

SET DIR=%~dp0%

::download install.ps1
%systemroot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "((new-object net.webclient).DownloadFile('','install.ps1'))"
::run installer
%systemroot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '%DIR%install.ps1' %*"

You can also get to this file by going to

If you prefer to have the install.ps1 file already, comment out the download line in the batch file and download the install.ps1 from and save it as install.ps1 next to the installChocolatey.cmd file.

Run installChocolatey.cmd from an elevated cmd.exe command prompt and it will install the latest version of Chocolatey. You can not run this from powershell.exe without making changes to your execution policy.

NOTE: To create and save a .cmd file, please use a text editor and nothing fancy like Microsoft Word or OneNote.

NuGet Package Manager Method

When you have Visual Studio 2010+ and the NuGet extension installed (pre-installed on any newer versions of Visual Studio), you can simply type the following three commands and you will have Chocolatey installed on your machine.

Install-Package chocolatey Initialize-Chocolatey Uninstall-Package chocolatey

NuGet.exe + PowerShell Method

You can also use NuGet command line to download Chocolatey:

nuget install chocolatey or nuget install chocolatey -pre

Once you download it, open PowerShell (remote unsigned), navigate to the tools folder and run:

& .\chocolateyInstall.ps1

Download + PowerShell Method

You can also just download and unzip the Chocolatey package (.nupkg is a fancy zip file):

  1. Download the Chocolatey package.
  2. Unzip it using any application that supports zip format.
  3. Open a PowerShell command shell and navigate into the unzipped package's tools folder.
  4. NOTE: Ensure PowerShell execution policy is set to at least bypass or remote signed (if you have issues, you may need to set it to Unrestricted).
  5. Call & .\chocolateyInstall.ps1 to allow Chocolatey to install.
  6. NOTE: This will not set Chocolatey as an installed package, so it may be a good idea to also call choco upgrade chocolatey -y and let it reinstall the same version, but at least it will be available for upgrades then.

Upgrading Chocolatey

Once installed, Chocolatey can be upgraded in exactly the same way as any other package that has been installed using Chocolatey. Simply use the command to upgrade to the latest stable release of Chocolatey:

choco upgrade chocolatey

Uninstalling Chocolatey

See uninstall.