# win_chocolatey – Manage packages using chocolatey

- Synopsis

- Requirements

- Parameters

- Notes

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Manage packages using Chocolatey.

- If Chocolatey is missing from the system, the module will install it.

## Requirements

The below requirements are needed on the host that executes this module.

- chocolatey >= 0.10.5 (will be upgraded if older)

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

allow_empty_checksums
boolean

Choices:
- no ←
- yes

Allow empty checksums to be used for downloaded resource from non-secure locations.
Use win_chocolatey_feature with the name `allowEmptyChecksums` to control this option globally.

allow_multiple
boolean
added in 2.8

Choices:
- no ←
- yes

Allow the installation of multiple packages when version is specified.
Having multiple packages at different versions can cause issues if the package doesn't support this. Use at your own risk.

allow_prerelease
boolean
added in 2.6

Choices:
- no ←
- yes

Allow the installation of pre-release packages.
If state is `latest`, the latest pre-release package will be installed.

architecture
string
added in 2.7

Choices:
- default ←
- x86

Force Chocolatey to install the package of a specific process architecture.
When setting `x86`, will ensure Chocolatey installs the x86 package even when on an x64 bit OS.

force
boolean

Choices:
- no ←
- yes

Forces the install of a package, even if it already is installed.
Using force will cause Ansible to always report that a change was made.

ignore_checksums
boolean

Choices:
- no ←
- yes

Ignore the checksums provided by the package.
Use win_chocolatey_feature with the name `checksumFiles` to control this option globally.

ignore_dependencies
boolean

Choices:
- no ←
- yes

Ignore dependencies, only install/upgrade the package itself.

install_args string |  | Arguments to pass to the native installer. These are arguments that are passed directly to the installer the Chocolatey package runs, this is generally an advanced option.
name list / required |  | Name of the package(s) to be installed. Set to `all` to run the action on all the installed packages.
package_params string |  | Parameters to pass to the package. These are parameters specific to the Chocolatey package and are generally documented by the package itself. Before Ansible 2.7, this option was just params. aliases: params

pinned
boolean
added in 2.8

Choices:
- no
- yes

Whether to pin the Chocolatey package or not.
If omitted then no checks on package pins are done.
Will pin/unpin the specific version if version is set.
Will pin the latest version of a package if `yes`, version is not set and and no pin already exists.
Will unpin all versions of a package if `no` and version is not set.
This is ignored when `state=absent`.

proxy_password string added in 2.4 |  | Proxy password used to install Chocolatey and the package. This value is exposed as a command argument and any privileged account can see this value when the module is running Chocolatey, define the password on the global config level with win_chocolatey_config with name `proxyPassword` to avoid this.
proxy_url string added in 2.4 |  | Proxy URL used to install chocolatey and the package. Use win_chocolatey_config with the name `proxy` to control this option globally.
proxy_username string added in 2.4 |  | Proxy username used to install Chocolatey and the package. Before Ansible 2.7, users with double quote characters `"` would need to be escaped with `\` beforehand. This is no longer necessary. Use win_chocolatey_config with the name `proxyUser` to control this option globally.

skip_scripts
boolean
added in 2.4

Choices:
- no ←
- yes

Do not run chocolateyInstall.ps1 or chocolateyUninstall.ps1 scripts when installing a package.

source
string

Specify the source to retrieve the package from.
Use win_chocolatey_source to manage global sources.
This value can either be the URL to a Chocolatey feed, a path to a folder containing `.nupkg` packages or the name of a source defined by win_chocolatey_source.
This value is also used when Chocolatey is not installed as the location of the install.ps1 script and only supports URLs for this case.

source_password string added in 2.7 |  | The password for source_username. This value is exposed as a command argument and any privileged account can see this value when the module is running Chocolatey, define the credentials with a source with win_chocolatey_source to avoid this.
source_username string added in 2.7 |  | A username to use with source when accessing a feed that requires authentication. It is recommended you define the credentials on a source with win_chocolatey_source instead of passing it per task.

state
string

Choices:
- absent
- downgrade
- latest
- present ←
- reinstalled

State of the package on the system.
When `absent`, will ensure the package is not installed.
When `present`, will ensure the package is installed.
When `downgrade`, will allow Chocolatey to downgrade a package if version is older than the installed version.
When `latest`, will ensure the package is installed to the latest available version.
When `reinstalled`, will uninstall and reinstall the package.

timeout integer | Default: 2700 | The time to allow chocolatey to finish before timing out. aliases: execution_timeout

validate_certs
boolean
added in 2.7

Choices:
- no
- yes ←

Used when downloading the Chocolatey install script if Chocolatey is not already installed, this does not affect the Chocolatey package install process.
When `no`, no SSL certificates will be validated.
This should only be used on personally controlled sites using self-signed certificate.

version
string

Specific version of the package to be installed.
When state is set to `absent`, will uninstall the specific version otherwise all versions of that package will be removed.
If a different version of package is installed, state must be `latest` or force set to `yes` to install the desired version.
Provide as a string (e.g. `'6.1'`), otherwise it is considered to be a floating-point number and depending on the locale could become `6,1`, which will cause a failure.
If name is set to `chocolatey` and Chocolatey is not installed on the host, this will be the version of Chocolatey that is installed. You can also set the `chocolateyVersion` environment var.

## Notes

Note

- This module will install or upgrade Chocolatey when needed.

- When using verbosity 2 or less (`-vv`) the `stdout` output will be restricted. When using verbosity 4 (`-vvvv`) the `stdout` output will be more verbose. When using verbosity 5 (`-vvvvv`) the `stdout` output will include debug output.

- Some packages, like hotfixes or updates need an interactive user logon in order to install. You can use `become` to achieve this, see Become and Windows. Even if you are connecting as local Administrator, using `become` to become Administrator will give you an interactive user logon, see examples below.

- If `become` is unavailable, use win_hotfix to install hotfixes instead of win_chocolatey as win_hotfix avoids using `wusa.exe` which cannot be run without `become`.

## See Also

See also

win_chocolatey_config – Manages Chocolatey config settings

  The official documentation on the win_chocolatey_config module.

win_chocolatey_facts – Create a facts collection for Chocolatey

  The official documentation on the win_chocolatey_facts module.

win_chocolatey_feature – Manages Chocolatey features

  The official documentation on the win_chocolatey_feature module.

win_chocolatey_source – Manages Chocolatey sources

  The official documentation on the win_chocolatey_source module.

win_feature – Installs and uninstalls Windows Features on Windows Server

  The official documentation on the win_feature module.

win_hotfix – Install and uninstalls Windows hotfixes

  Use when `become` is unavailable, to avoid using `wusa.exe`.

win_package – Installs/uninstalls an installable package

  The official documentation on the win_package module.

win_updates – Download and install Windows updates

  The official documentation on the win_updates module.

Chocolatey website

  More information about the Chocolatey tool.

Chocolatey packages

  An overview of the available Chocolatey packages.

Become and Windows

  Some packages, like hotfixes or updates need an interactive user logon in order to install. You can use `become` to achieve this.

## Examples

    - name: Install git
      win_chocolatey:
        name: git
        state: present

    - name: Upgrade installed packages
      win_chocolatey:
        name: all
        state: latest

    - name: Install notepadplusplus version 6.6
      win_chocolatey:
        name: notepadplusplus
        version: '6.6'

    - name: Install notepadplusplus 32 bit version
      win_chocolatey:
        name: notepadplusplus
        architecture: x86

    - name: Install git from specified repository
      win_chocolatey:
        name: git
        source: https://someserver/api/v2/

    - name: Install git from a pre configured source (win_chocolatey_source)
      win_chocolatey:
        name: git
        source: internal_repo

    - name: Ensure Chocolatey itself is installed and use internal repo as source
      win_chocolatey:
        name: chocolatey
        source: http://someserver/chocolatey

    - name: Uninstall git
      win_chocolatey:
        name: git
        state: absent

    - name: Install multiple packages
      win_chocolatey:
        name:
        - procexp
        - putty
        - windirstat
        state: present

    - name: Install multiple packages sequentially
      win_chocolatey:
        name: '{{ item }}'
        state: present
      loop:
      - procexp
      - putty
      - windirstat

    - name: Uninstall multiple packages
      win_chocolatey:
        name:
        - procexp
        - putty
        - windirstat
        state: absent

    - name: Install curl using proxy
      win_chocolatey:
        name: curl
        proxy_url: http://proxy-server:8080/
        proxy_username: joe
        proxy_password: p@ssw0rd

    - name: Install a package that requires 'become'
      win_chocolatey:
        name: officepro2013
      become: yes
      become_user: Administrator
      become_method: runas

    - name: install and pin Notepad++ at 7.6.3
      win_chocolatey:
        name: notepadplusplus
        version: 7.6.3
        pinned: yes
        state: present

    - name: remove all pins for Notepad++ on all versions
      win_chocolatey:
        name: notepadplusplus
        pinned: no
        state: present

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
command string | changed | The full command used in the chocolatey task. Sample: choco.exe install -r --no-progress -y sysinternals --timeout 2700 --failonunfound
rc integer | always | The return code from the chocolatey task.
stdout string | changed | The stdout from the chocolatey task. The verbosity level of the messages are affected by Ansible verbosity setting, see notes for more details. Sample: Chocolatey upgraded 1/1 packages.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Trond Hindenes (@trondhindenes)

- Peter Mounce (@petemounce)

- Pepe Barbe (@elventear)

- Adam Keech (@smadam813)

- Pierre Templier (@ptemplier)

- Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.