Installation Guide

• Installation Guide
• Installing Ansible on specific operating systems
• Configuring Ansible
• Installing Ansible<span id="installation_guide"></span>

Installation Guide

Welcome to the Ansible Installation Guide!

Installing Ansible on specific operating systems

[!NOTE] These instructions come from their respective communities. If you encounter bugs or issues, file them with that community to update these instructions. Ansible maintains only the pip install instructions.

You can always install the ansible package from PyPI using pip <intro_installation_guide> on most systems. The community also packages and maintains Ansible for various Linux distributions.

This guide shows you how to install Ansible from different distribution package repositories.

Requirements for adding new distributions

Package maintainers who want to add instructions for another distribution to this guide must meet the following requirements:

• Ensure the distribution provides a reasonably up-to-date version of ansible.
• Keep ansible-core and ansible versions synchronized to the extent that the build system allows.
• Provide a way to contact the distribution maintainers as part of the instructions.
• Distribution maintainers are also encouraged to join and monitor the Ansible Packaging Matrix room.

Installing Ansible on Fedora Linux

Fedora Linux provides both the full Ansible package and the minimal ansible-core package through the standard repositories.

Install the full ansible package:

$ sudo dnf install ansible

Install the minimal ansible-core package:

$ sudo dnf install ansible-core

Fedora repositories include several Ansible collections as standalone packages that you can install alongside ansible-core. For example, install the community.general collection:

$ sudo dnf install ansible-collection-community-general

See the Fedora Packages index for a complete list of Ansible collections packaged in Fedora.

Contact the package maintainers by filing a bug against the Fedora product in Red Hat Bugzilla.

Installing Ansible from EPEL

If you use CentOS Stream, Almalinux, Rocky Linux, or related distributions, you can install ansible or Ansible collections from the community-maintained EPEL (Extra Packages for Enterprise Linux) repository:

1. Enable the EPEL repository.
2. Use the same dnf commands as for Fedora Linux.

Contact the package maintainers by filing a bug against the Fedora EPEL product in Red Hat Bugzilla.

Installing Ansible on OpenSUSE Tumbleweed/Leap

OpenSUSE provides Ansible packages through the standard package manager.

$ sudo zypper install ansible

See the OpenSUSE Support Portal for additional help with Ansible on OpenSUSE.

Installing Ansible on Ubuntu

Ubuntu provides Ansible packages through a Personal Package Archive (PPA) that contains more recent versions than the standard repositories.

Ubuntu builds are available in a PPA here.

Configure the PPA on your system and install Ansible:

$ sudo apt update
$ sudo apt install software-properties-common
$ sudo add-apt-repository --yes --update ppa:ansible/ansible
$ sudo apt install ansible

File any issues in the PPA's issue tracker.

Installing Ansible on Debian

Debian users can choose between the standard repository or the Ubuntu PPA for more recent versions.

While Ansible is available from the main Debian repository, this version can be outdated.

For a more recent version, Debian users can use the Ubuntu PPA according to the following table:

Debian		Ubuntu	UBUNTU_CODENAME
Debian 13 (Trixie)	->	Ubuntu 24.04 (Noble)	noble
Debian 12 (Bookworm)	->	Ubuntu 22.04 (Jammy)	jammy
Debian 11 (Bullseye)	->	Ubuntu 20.04 (Focal)	focal

The following example assumes that you already have wget and gpg installed.

Add the repository and install Ansible. Set UBUNTU_CODENAME=... based on the table above (we use noble in this example):

$ UBUNTU_CODENAME='noble'
$ FINGERPRINT='6125E2A8C77F2818FB7BD15B93C4A3FD7BB9C367'

$ wget -O- "https://keyserver.ubuntu.com/pks/lookup?fingerprint=on&op=get&search=0x${FINGERPRINT}" | sudo gpg --dearmor -o /usr/share/keyrings/ansible-archive-keyring.gpg

$ cat <<EOF | sudo tee /etc/apt/sources.list.d/ansible.sources > /dev/null
Types: deb
URIs: https://ppa.launchpadcontent.net/ansible/ansible/ubuntu/
Suites: ${UBUNTU_CODENAME}
Components: main
Trusted: yes
Signed-By: /usr/share/keyrings/ansible-archive-keyring.gpg
EOF

$ sudo apt update && sudo apt install ansible

[!NOTE] Use double quotes around the keyserver URL and in the "echo deb" command like in the example above.

These commands download the signing key and add an entry to apt's sources pointing to the PPA.

Previously, you may have used apt-key add. The apt-key add approach is now deprecated for security reasons (on Debian, Ubuntu, and elsewhere).

As such, we do NOT add the key to /etc/apt/trusted.gpg.d/ or to /etc/apt/trusted.gpg where the key would be allowed to sign releases from ANY repository.

Installing Ansible on Arch Linux

Arch Linux provides both the full Ansible package and ansible-core through the standard package repositories.

Install the full ansible package:

$ sudo pacman -S ansible

Install the minimal ansible-core package:

$ sudo pacman -S ansible-core

Arch Linux repositories include several Ansible ecosystem packages as standalone packages that you can install alongside ansible-core. See the Arch Linux Packages index for a complete list of Ansible packages in Arch Linux.

Contact the package maintainers by opening an issue in the related package GitLab repository.

Installing Ansible on Windows

You cannot use a Windows system for the Ansible control node. See windows_control_node

Configuring Ansible

This topic describes how to control Ansible settings.

Configuration file

Certain settings in Ansible are adjustable with a configuration file (ansible.cfg). The stock configuration should be sufficient for most users, but there may be reasons you would want to change them.

Paths where the configuration file is searched are listed in reference documentation<ansible_configuration_settings_locations>.

Getting the latest configuration

If installing Ansible from a package manager, the latest ansible.cfg file should be present in /etc/ansible, possibly as a .rpmnew file (or other) as appropriate in the case of updates.

If you installed Ansible from pip or from the source, you may want to create this file to override default settings in Ansible.

You can generate an Ansible configuration file, ansible.cfg, that lists all default settings as follows:

$ ansible-config init --disabled > ansible.cfg

Include available plugins to create a more complete Ansible configuration as follows:

$ ansible-config init --disabled -t all > ansible.cfg

For more details and a full listing of available configurations go to configuration_settings<ansible_configuration_settings>.

You can use the ansible-config command-line utility to list your available options and inspect the current values.

For in-depth details, see ansible_configuration_settings.

Environmental configuration

Ansible also allows configuring settings using environment variables.

If these environment variables are set, they will override any associated settings loaded from the configuration file. You can get a full listing of available environment variables from:

• ansible_configuration_settings: for configuring core functionality
• list_of_collection_env_vars: for configuring plugins in collections

Command line options

Not all configuration options are present in the command line, just the ones deemed most useful or common. Settings in the command line will override those passed through the configuration file and the environment.

The full list of options available is in ansible-playbook and ansible.

Installing Ansible<span id="installation_guide"></span>

Ansible is an agentless automation tool that you install on a single host (referred to as the control node).

From the control node, Ansible can manage an entire fleet of machines and other devices (referred to as managed nodes) remotely with SSH, Powershell remoting, and numerous other transports, all from a simple command-line interface with no databases or daemons required.

Control node requirements

For your control node (the machine that runs Ansible), you can use nearly any UNIX-like machine with Python installed. This includes Red Hat, Debian, Ubuntu, macOS, BSDs, and Windows under a Windows Subsystem for Linux (WSL) distribution. Windows without WSL is not natively supported as a control node; see Matt Davis' blog post for more information.

Managed node requirements

The managed node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python to run Ansible-generated Python code. The managed node also needs a user account that can connect through SSH to the node with an interactive POSIX shell.

[!NOTE] There can be exceptions in module requirements. For example, network modules do not require Python on the managed device. See documentation for the modules you use.

Node requirement summary

You can find details about control and managed node requirements, including Python versions, for each Ansible version in the support_life and ansible_core_support_matrix sections.

Selecting an Ansible package and version to install

Ansible's community packages are distributed in two ways:

• ansible-core: a minimalist language and runtime package containing a set of built-in modules and plugins<plugins_in_ansible.builtin>.
• ansible: a much larger "batteries included" package, which adds a community-curated selection of Ansible Collections <collections> for automating a wide variety of devices.

Choose the package that fits your needs. The following instructions use ansible as a package name, but you can substitute ansible-core if you prefer to start with the minimal package and separately install only the Ansible Collections you require.

The ansible or ansible-core packages may be available in your operating systems package manager, and you are free to install these packages with your preferred method. For more information, see the installing_distros guide. These installation instructions only cover the officially supported means of installing the python packages with pip.

See the Ansible package release status table<ansible_changelogs> for the ansible-core version included in the package.

Installing and upgrading Ansible with pipx

On some systems, it may not be possible to install Ansible with pip, due to decisions made by the operating system developers. In such cases, pipx is a widely available alternative.

These instructions will not go over the steps to install pipx; if those instructions are needed, please continue to the pipx installation instructions for more information.

Installing Ansible

Use pipx in your environment to install the full Ansible package:

$ pipx install --include-deps ansible

You can install the minimal ansible-core package:

$ pipx install ansible-core

Alternately, you can install a specific version of ansible-core:

$ pipx install ansible-core==2.12.3

Upgrading Ansible

To upgrade an existing Ansible installation to the latest released version:

$ pipx upgrade --include-injected ansible

Installing Extra Python Dependencies

To install additional python dependencies that may be needed, with the example of installing the argcomplete python package as described below:

$ pipx inject ansible argcomplete

Include the --include-apps option to make apps in the additional python dependency available on your PATH. This allows you to execute commands for those apps from the shell.

$ pipx inject --include-apps ansible argcomplete

If you need to install dependencies from a requirements file, for example when installing the Azure collection, you can use runpip.

$ pipx runpip ansible install -r ~/.ansible/collections/ansible_collections/azure/azcollection/requirements.txt

Installing and upgrading Ansible with pip

Locating Python

Locate and remember the path to the Python interpreter you wish to use to run Ansible. The following instructions refer to this Python as python3. For example, if you have determined that you want the Python at /usr/bin/python3.9 to be the one that you will install Ansible under, specify that instead of python3.

Ensuring pip is available

To verify whether pip is already installed for your preferred Python:

$ python3 -m pip -V

If all is well, you should see something like the following:

$ python3 -m pip -V
pip 21.0.1 from /usr/lib/python3.9/site-packages/pip (python 3.9)

If so, pip is available, and you can move on to the next step <pip_install>.

If you see an error like No module named pip, you will need to install pip under your chosen Python interpreter before proceeding. This may mean installing an additional OS package (for example, python3-pip), or installing the latest pip directly from the Python Packaging Authority by running the following:

$ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
$ python3 get-pip.py --user

You may need to perform some additional configuration before you are able to run Ansible. See the Python documentation on installing to the user site for more information.

Installing Ansible

Use pip in your selected Python environment to install the full Ansible package for the current user:

$ python3 -m pip install --user ansible

You can install the minimal ansible-core package for the current user:

$ python3 -m pip install --user ansible-core

Alternately, you can install a specific version of ansible-core:

$ python3 -m pip install --user ansible-core==2.12.3

Upgrading Ansible

To upgrade an existing Ansible installation in this Python environment to the latest released version, simply add --upgrade to the command above:

$ python3 -m pip install --upgrade --user ansible

Installing Ansible to containers

Instead of installing Ansible content manually, you can simply build an execution environment container image or use one of the available community images as your control node. See getting_started_ee_index for details.

Installing for development

If you are testing new features, fixing bugs, or otherwise working with the development team on changes to the core code, you can install and run the source from GitHub.

[!NOTE] You should only install and run the devel branch if you are modifying ansible-core or trying out features under development. This is a rapidly changing source of code and can become unstable at any point.

For more information on getting involved in the Ansible project, see the ansible_community_guide.

For more information on creating Ansible modules and Collections, see the developer_guide.

Installing devel from GitHub with pip

You can install the devel branch of ansible-core directly from GitHub with pip:

$ python3 -m pip install --user https://github.com/ansible/ansible/archive/devel.tar.gz

You can replace devel in the URL mentioned above, with any other branch or tag on GitHub to install older versions of Ansible, tagged alpha or beta versions, and release candidates.

Running the devel branch from a clone

ansible-core is easy to run from source. You do not need root permissions to use it and there is no software to actually install. No daemons or database setup are required.

1. Clone the ansible-core repository

   $ git clone https://github.com/ansible/ansible.git
   $ cd ./ansible
   

2. Setup the Ansible environment

   • Using Bash

     $ source ./hacking/env-setup
     

   • Using Fish

     $ source ./hacking/env-setup.fish
     

   • To suppress spurious warnings/errors, use -q

     $ source ./hacking/env-setup -q
     

3. Install Python dependencies

   $ python3 -m pip install --user -r ./requirements.txt
   

4. Update the devel branch of ansible-core on your local machine

   Use pull-with-rebase so any local changes are replayed.

   $ git pull --rebase
   

Confirming your installation

You can test that Ansible is installed correctly by checking the version:

$ ansible --version

The version displayed by this command is for the associated ansible-core package that has been installed.

To check the version of the ansible package that has been installed:

$ ansible-community --version

Adding Ansible command shell completion

You can add shell completion of the Ansible command line utilities by installing an optional dependency called argcomplete. It supports bash, and has limited support for zsh and tcsh.

For more information about installation and configuration, see the argcomplete documentation.

Installing argcomplete

If you chose the pipx installation instructions:

$ pipx inject --include-apps ansible argcomplete

If you chose the pip installation instructions:

$ python3 -m pip install --user argcomplete

Configuring argcomplete

There are 2 ways to configure argcomplete to allow shell completion of the Ansible command line utilities: globally or per command.

Global configuration

Global completion requires bash 4.2.

$ activate-global-python-argcomplete --user

This will write a bash completion file to a user location. Use --dest to change the location or sudo to set up the completion globally.

Per command configuration

If you do not have bash 4.2, you must register each script independently.

$ eval $(register-python-argcomplete ansible)
$ eval $(register-python-argcomplete ansible-config)
$ eval $(register-python-argcomplete ansible-console)
$ eval $(register-python-argcomplete ansible-doc)
$ eval $(register-python-argcomplete ansible-galaxy)
$ eval $(register-python-argcomplete ansible-inventory)
$ eval $(register-python-argcomplete ansible-playbook)
$ eval $(register-python-argcomplete ansible-pull)
$ eval $(register-python-argcomplete ansible-vault)

You should place the above commands into your shell's profile file such as ~/.profile or ~/.bash_profile.

Using argcomplete with zsh or tcsh

See the argcomplete documentation.