Note
This plugin is part of the chocolatey.chocolatey collection (version 1.1.0).
You might already have this collection installed if you are using the ansible
package. It is not included in ansible-core
. To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install chocolatey.chocolatey
.
To use it in a playbook, specify: chocolatey.chocolatey.win_chocolatey
.
New in version 0.1.9: of chocolatey.chocolatey
The below requirements are needed on the host that executes this module.
Parameter | Choices/Defaults | Comments |
---|---|---|
allow_empty_checksums boolean added in 0.2.2 of chocolatey.chocolatey |
| Allow empty checksums to be used for downloaded resource from non-secure locations. Use M(win_chocolatey_feature) with the name allowEmptyChecksums to control this option globally. |
allow_multiple boolean added in 0.2.8 of chocolatey.chocolatey |
| 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. The value of this parameter is ignored if state is absent . Instead, this parameter is automatically configured to remove all versions if version is not specified, and the specific version only if version is specified. |
allow_prerelease boolean added in 0.2.6 of chocolatey.chocolatey |
| Allow the installation of pre-release packages. If state is latest , the latest pre-release package will be installed. |
architecture string added in 0.2.7 of chocolatey.chocolatey |
| 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 |
| 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 added in 0.2.2 of chocolatey.chocolatey |
| Ignore the checksums provided by the package. Use M(win_chocolatey_feature) with the name checksumFiles to control this option globally. |
ignore_dependencies boolean added in 0.2.1 of chocolatey.chocolatey |
| Ignore dependencies, only install/upgrade the package itself. |
install_args string added in 0.2.1 of chocolatey.chocolatey | 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 / elements=string / required | Name of the package(s) to be installed. Set to all to run the action on all the installed packages. | |
override_args boolean added in 0.2.10 of chocolatey.chocolatey |
| Override arguments of native installer with arguments provided by user. Should install arguments be used exclusively without appending to current package passed arguments. |
package_params string added in 0.2.1 of chocolatey.chocolatey | 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 0.2.8 of chocolatey.chocolatey |
| 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 0.2.4 of chocolatey.chocolatey | 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 M(win_chocolatey_config) with name proxyPassword to avoid this. | |
proxy_url string added in 0.2.4 of chocolatey.chocolatey | Proxy URL used to install chocolatey and the package. Use M(win_chocolatey_config) with the name proxy to control this option globally. | |
proxy_username string added in 0.2.4 of chocolatey.chocolatey | 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 M(win_chocolatey_config) with the name proxyUser to control this option globally. | |
remove_dependencies boolean added in 1.1.0 of chocolatey.chocolatey |
| Remove a package's dependencies on uninstall. |
skip_scripts boolean added in 0.2.4 of chocolatey.chocolatey |
| Do not run chocolateyInstall.ps1 or chocolateyUninstall.ps1 scripts when installing a package. |
source string | Specify the source to retrieve the package from. Use M(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 M(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 0.2.7 of chocolatey.chocolatey | 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 M(win_chocolatey_source) to avoid this. | |
source_username string added in 0.2.7 of chocolatey.chocolatey | A username to use with source when accessing a feed that requires authentication. It is recommended you define the credentials on a source with M(win_chocolatey_source) instead of passing it per task. | |
state string |
| 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 added in 0.2.3 of chocolatey.chocolatey | Default: 2700 | The time to allow chocolatey to finish before timing out. aliases: execution_timeout |
validate_certs boolean added in 0.2.7 of chocolatey.chocolatey |
| 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. |
Note
-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.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.become
is unavailable, use M(win_hotfix) to install hotfixes instead of M(win_chocolatey) as M(win_hotfix) avoids using wusa.exe
which cannot be run without become
.See also
The official documentation on the win_chocolatey_config module.
The official documentation on the win_chocolatey_facts module.
The official documentation on the win_chocolatey_feature module.
The official documentation on the win_chocolatey_source module.
The official documentation on the win_feature module.
Use when become
is unavailable, to avoid using wusa.exe
.
The official documentation on the win_package module.
The official documentation on the win_updates module.
More information about the Chocolatey tool.
An overview of the available Chocolatey packages.
Some packages, like hotfixes or updates need an interactive user logon in order to install. You can use become
to achieve this.
- 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: Uninstall a package and dependencies win_chocolatey: name: audacity-lame remove_dependencies: yes 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
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. |
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/chocolatey/chocolatey/win_chocolatey_module.html