chocolatey.chocolatey.win_chocolatey module – Manage packages using chocolatey
Note
This module is part of the chocolatey.chocolatey collection (version 1.4.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
.
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.
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. 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: |
|
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:
|
|
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 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. 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. |
|
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 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
) thestdout
output will be restricted. When using verbosity 4 (-vvvv
) thestdout
output will be more verbose. When using verbosity 5 (-vvvvv
) thestdout
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 :ref:`become_windows`. Even if you are connecting as local Administrator, usingbecome
to become Administrator will give you an interactive user logon, see examples below.If
become
is unavailable, use community.windows.win_hotfix to install hotfixes instead of chocolatey.chocolatey.win_chocolatey as community.windows.win_hotfix avoids usingwusa.exe
which cannot be run withoutbecome
.
See Also
See also
- chocolatey.chocolatey.win_chocolatey_config
The official documentation on the chocolatey.chocolatey.win_chocolatey_config module.
- chocolatey.chocolatey.win_chocolatey_facts
The official documentation on the chocolatey.chocolatey.win_chocolatey_facts module.
- chocolatey.chocolatey.win_chocolatey_feature
The official documentation on the chocolatey.chocolatey.win_chocolatey_feature module.
- chocolatey.chocolatey.win_chocolatey_source
The official documentation on the chocolatey.chocolatey.win_chocolatey_source module.
- community.windows.win_feature
The official documentation on the community.windows.win_feature module.
- community.windows.win_hotfix
Use when
become
is unavailable, to avoid usingwusa.exe
.- community.windows.win_package
The official documentation on the community.windows.win_package module.
- community.windows.win_updates
The official documentation on the community.windows.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, 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: yes
state: absent
- name: Install curl using proxy
win_chocolatey:
name: curl
proxy_url: http://proxy-server:8080/
proxy_username: joe
proxy_password: [email protected]
- 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
- 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'
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: |