chocolatey.chocolatey.win_chocolatey module – Manage packages using chocolatey
Note
This module is part of the chocolatey.chocolatey collection (version 1.5.3).
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.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: chocolatey.chocolatey.win_chocolatey.
New in chocolatey.chocolatey 0.1.9
Synopsis
Manage packages using Chocolatey.
If Chocolatey is missing from the system, the module will install it.
If there are multiple installations of choco.exe in env:PATH, it will use the first found one
Requirements
The below requirements are needed on the host that executes this module.
chocolatey >= 0.10.5 (will be upgraded if older)
Parameters
Parameter |
Comments |
|---|---|
Allow empty checksums to be used for downloaded resource from non-secure locations. Use chocolatey.chocolatey.win_chocolatey_feature with the name Choices:
|
|
This option is deprecated and will be removed in v2.0.0 of this collection. Chocolatey CLI has deprecated side-by-side installations as of its v1.2.0 release and plans to remove them in its v2.0.0 release. Chocolatey CLI (choco) v2.0.0 and higher do not support this option. This module will return an error if this option is enabled and the installed version of Chocolatey CLI on the client is v2.0.0 or higher. 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 Choices:
|
|
Allow the installation of pre-release packages. If state is Choices:
|
|
Force Chocolatey to install the package of a specific process architecture. When setting Choices:
|
|
Specify the bootstrap script URL that can be used to install Chocolatey if it is not already present on the system. Use this parameter when name is If neither this parameter nor source is set, the bootstrap script url will be If this parameter is not set, and source is set to a url, the bootstrap script url will be determined from that url instead. This parameter only defines which bootstrap script is used to download and install Chocolatey. To define the URL to a specific Chocolatey nupkg to install, note that many bootstrap scripts respect the value of the |
|
Specify the TLS versions used when retrieving and invoking the bootstrap_script to install Chocolatey if it is not already installed on the system. Does not change the TLS versions used by Chocolatey itself after it has already been installed. Specified TLS versions may be ignored or unused if the target TLS version is not available on the client. Choices:
Default: |
|
Override a package’s checksums for files downloaded during installation. If the checksum is not MD5, you will need to specify the checksum_type as well. |
|
Override a package’s checksums for 64-bit files downloaded during installation. If the checksum is not MD5, you will need to specify the checksum_type64 as well. |
|
Override a package’s checksum type for files downloaded during install. Use in conjunction with checksum. Choices:
|
|
Override a package’s checksum type for files downloaded during install. Use in conjunction with checksum64. Choices:
|
|
Additional parameters to pass to choco.exe These may be any additional parameters to pass through directly to Chocolatey, in addition to the arguments already specified via other parameters. This may be used to pass licensed options to Chocolatey, for example Passing licensed options may result in them being ignored or causing errors if the targeted node is unlicensed or missing the chocolatey.extension package. |
|
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. Choices:
|
|
Ignore the checksums provided by the package. Use chocolatey.chocolatey.win_chocolatey_feature with the name Choices:
|
|
Ignore dependencies, only install/upgrade the package itself. Choices:
|
|
These are arguments that are passed directly to the installer run by the Chocolatey package, for example MSI properties or command-line arguments for the specific native installer used by the package. For parameters that need to be passed to the chocolateyInstall script for the Chocolatey package itself, use package_params. |
|
Name of the package(s) to be installed. Set to |
|
Override arguments of native installer with arguments provided by user. Should install arguments be used exclusively without appending to current package passed arguments. Choices:
|
|
Parameters to pass to the package’s chocolateyInstall script. These are parameters specific to the Chocolatey package and are generally documented by the package itself. For parameters that should be passed directly to the underlying installer (for example, MSI installer properties and arguments), use install_args instead. |
|
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 Will unpin all versions of a package if This is ignored when Choices:
|
|
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 chocolatey.chocolatey.win_chocolatey_config with name |
|
Proxy URL used to install chocolatey and the package. Use chocolatey.chocolatey.win_chocolatey_config with the name |
|
Proxy username used to install Chocolatey and the package. Before Ansible 2.7, users with double quote characters Use chocolatey.chocolatey.win_chocolatey_config with the name |
|
Remove a package’s dependencies on uninstall. Choices:
|
|
Do not run chocolateyInstall.ps1 or chocolateyUninstall.ps1 scripts when installing a package. Choices:
|
|
Specify the source to retrieve the package from. Use chocolatey.chocolatey.win_chocolatey_source to manage global sources. This value can either be the URL to a Chocolatey feed, a path to a folder containing When Chocolatey is not yet installed, prefer using bootstrap_script instead to determine where to pull the bootstrap script from. This value may also be used when Chocolatey is not installed as the location of the install.ps1 script if bootstrap_script is not set, and only supports URLs for this case. In this case, if the URL ends in “.ps1”, it is used as-is. Otherwise, if the URL appears to contain a “/repository/” fragment, the module will attempt to append “/install.ps1” to find an install script. If neither of these checks pass, the module will strip off the URL path and try to find an “/install.ps1” from the root of the server. |
|
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 chocolatey.chocolatey.win_chocolatey_source to avoid this. |
|
A username to use with source when accessing a feed that requires authentication. It is recommended you define the credentials on a source with chocolatey.chocolatey.win_chocolatey_source instead of passing it per task. |
|
State of the package on the system. When When When When When Choices:
|
|
The time (in seconds) to allow chocolatey to finish before timing out. Default: |
|
Used when downloading the Chocolatey install script if Chocolatey is not already installed, this does not affect the Chocolatey package install process. When This should only be used on personally controlled sites using self-signed certificate. Choices:
|
|
Specific version of the package to be installed. When state is set to When state is set to If a different version of package is already installed, state must be Provide as a string (e.g. If name is set to |
Notes
Note
This module will install or upgrade Chocolatey when needed.
When using verbosity 2 or less (
-vv) thestdoutoutput will be restricted. When using verbosity 4 (-vvvv) thestdoutoutput will be more verbose. When using verbosity 5 (-vvvvv) thestdoutoutput will include debug output.Some packages, like hotfixes or updates need an interactive user logon in order to install. You can use
becometo achieve this, see :ref:`become_windows`. Even if you are connecting as local Administrator, usingbecometo become Administrator will give you an interactive user logon, see examples below.If
becomeis unavailable, use ansible.windows.win_hotfix to install hotfixes instead of chocolatey.chocolatey.win_chocolatey as ansible.windows.win_hotfix avoids usingwusa.exewhich cannot be run withoutbecome.From Chocolatey CLI 2.0.0 and above, the minimum .NET Framework version required was changed to .NET Framework 4.8. If this requirement is not met, and a 1.x version of Chocolatey CLI is not specified, then chocolatey.chocolatey.win_chocolatey will not attempt to install Chocolatey CLI. See the examples section below for one method of meeting the .NET Framework 4.8 requirement and also refer to the Chocolatey documentation for more information about Chocolatey CLI 2.0.0.
See Also
See also
- chocolatey.chocolatey.win_chocolatey_config
Manages Chocolatey config settings.
- chocolatey.chocolatey.win_chocolatey_facts
Create a facts collection for Chocolatey.
- chocolatey.chocolatey.win_chocolatey_feature
Manages Chocolatey features.
- chocolatey.chocolatey.win_chocolatey_source
Manages Chocolatey sources.
- ansible.windows.win_feature
Installs and uninstalls Windows Features on Windows Server.
- ansible.windows.win_hotfix
Use when
becomeis unavailable, to avoid usingwusa.exe.- ansible.windows.win_package
Installs/uninstalls an installable package.
- ansible.windows.win_updates
Download and install Windows updates.
- 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
becometo 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, using community repo for the bootstrap
win_chocolatey:
name: chocolatey
- name: Ensure Chocolatey itself is installed, bootstrapping with a specific nupkg url
win_chocolatey:
name: chocolatey
environment:
chocolateyDownloadUrl: "https://internal-web-server/files/chocolatey.1.1.0.nupkg"
- name: Ensure Chocolatey itself is installed and use internal repo as source for bootstrap script
win_chocolatey:
name: chocolatey
source: http://someserver/chocolatey
- name: Ensure Chocolatey itself is installed, using a specific bootstrap script
win_chocolatey:
name: chocolatey
bootstrap_script: https://internal-web-server/files/custom-chocolatey-install.ps1
- name: Ensure Chocolatey itself is installed, using a specific bootstrap script and target nupkg
win_chocolatey:
name: chocolatey
bootstrap_script: https://internal-web-server/files/custom-chocolatey-install.ps1
environment:
chocolateyDownloadUrl: "https://internal-web-server/files/chocolatey.1.1.0.nupkg"
- 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: true
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: true
become_user: Administrator
become_method: runas
- name: install and pin Notepad++ at 7.6.3
win_chocolatey:
name: notepadplusplus
version: 7.6.3
pinned: true
state: present
- name: remove all pins for Notepad++ on all versions
win_chocolatey:
name: notepadplusplus
pinned: false
state: present
- name: install a package with options that require licensed edition
win_chocolatey:
name: foo
state: present
choco_args:
- --skip-download-cache
- --package-parameters-sensitive
- '/Password=SecretPassword'
- name: ensure .NET Framework 4.8 requirement is satisfied for Chocolatey CLI v2.0.0+
block:
- name: install Chocolatey CLI v1.4.0
win_chocolatey:
name: 'chocolatey'
state: present
version: '1.4.0'
- name: install Microsoft .NET Framework 4.8
win_chocolatey:
name: 'netfx-4.8'
state: present
- name: Reboot the host to complete .NET Framework 4.8 install
ansible.windows.win_reboot:
- name: install Chocolatey CLI v2.0.0+ when .NET Framework 4.8 dependency is met
win_chocolatey:
name: 'chocolatey'
state: latest
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The full command used in the chocolatey task. Returned: changed Sample: |
|
The return code from the chocolatey task. Returned: always Sample: |
|
The stdout from the chocolatey task. The verbosity level of the messages are affected by Ansible verbosity setting, see notes for more details. Returned: changed Sample: |