Documentation

win_chocolatey - Manage packages using chocolatey

New in version 1.9.

Synopsis

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
(added in 2.2)
    Choices:
  • no ←
  • yes
Allow empty checksums to be used.
force
    Choices:
  • no ←
  • yes
Forces install of the package (even if it already exists).
Using force will cause ansible to always report that a change was made.
ignore_checksums
(added in 2.2)
    Choices:
  • no ←
  • yes
Ignore checksums altogether.
ignore_dependencies
(added in 2.1)
    Choices:
  • no ←
  • yes
Ignore dependencies, only install/upgrade the package itself.
install_args
(added in 2.1)
Arguments to pass to the native installer.
name
required
Name of the package to be installed.
This must be a single package name.
params
(added in 2.1)
Parameters to pass to the package
proxy_password
(added in 2.4)
Proxy password used to install chocolatey and the package.
See notes in proxy_username when dealing with double quotes in a password.
proxy_url
(added in 2.4)
Proxy url used to install chocolatey and the package.
proxy_username
(added in 2.4)
Proxy username used to install chocolatey and the package.
When dealing with a username with double quote characters ", they need to be escaped with \ beforehand. See examples for more details.
skip_scripts
(added in 2.4)
    Choices:
  • no ←
  • yes
Do not run chocolateyInstall.ps1 or chocolateyUninstall.ps1 scripts.
source
Specify source rather than using default chocolatey repository.
state
    Choices:
  • absent
  • downgrade
  • latest
  • present ←
  • reinstalled
State of the package on the system.
timeout
(added in 2.3)
Default:
2700
The time to allow chocolatey to finish before timing out.

aliases: execution_timeout
upgrade
    Choices:
  • no ←
  • yes
If package is already installed it, try to upgrade to the latest version or to the specified version.
As of Ansible v2.3 this is deprecated, set parameter state to latest for the same result.
version
Specific version of the package to be installed.
Ignored when state is set to absent.

Notes

Note

  • Provide the version parameter value 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.
  • 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.
  • This module will install or upgrade Chocolatey when needed.
  • Some packages need an interactive user logon in order to install. You can use (become) to achieve this.
  • Even if you are connecting as local Administrator, using (become) to become Administrator will give you an interactive user logon, see examples below.
  • Use (win_hotfix to install hotfixes instead of (win_chocolatey) as (win_hotfix) avoids using wusa.exe which cannot be run remotely.

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.install
    version: '6.6'

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

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

- name: Install multiple packages
  win_chocolatey:
    name: '{{ item }}'
    state: present
  with_items:
  - pscx
  - windirstat

- name: uninstall multiple packages
  win_chocolatey:
    name: '{{ item }}'
    state: absent
  with_items:
  - pscx
  - windirstat

- name: Install curl using proxy
  win_chocolatey:
    name: curl
    proxy_url: http://proxy-server:8080/
    proxy_username: joe
    proxy_password: [email protected]

- name: Install curl with proxy credentials that contain quotes
  win_chocolatey:
    name: curl
    proxy_url: http://proxy-server:8080/
    proxy_username: user with \"escaped\" double quotes
    proxy_password: pass with \"escaped\" double quotes

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

Return Values

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

Key
Returned
Description
choco_bootstrap_output
str
changed, choco task returned a failure
DEPRECATED, will be removed in 2.6, use stdout instead.

Sample:
Chocolatey upgraded 1/1 packages.
choco_error_cmd
str
changed, choco task returned a failure
DEPRECATED, will be removed in 2.6, use command instead.

Sample:
choco.exe install -r --no-progress -y sysinternals --timeout 2700 --failonunfound
choco_error_log
str
changed, choco task returned a failure
DEPRECATED, will be removed in 2.6, use stdout instead.

Sample:
sysinternals not installed. The package was not found with the source(s) listed
command
str
changed
The full command used in the chocolatey task.

Sample:
choco.exe install -r --no-progress -y sysinternals --timeout 2700 --failonunfound
rc
int
changed
The return code from the chocolatey task.

stdout
str
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 flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author

  • Trond Hindenes (@trondhindenes)
  • Peter Mounce (@petemounce)
  • Pepe Barbe (@elventear)
  • Adam Keech (@smadam813)
  • Pierre Templier (@ptemplier)

Hint

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