This page describes how to install Ansible on different platforms.
Ansible is an agentless automation tool that by default manages machines over the SSH protocol. Once installed, Ansible does
not add a database, and there will be no daemons to start or keep running. You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point. When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
Welcome to the Ansible Installation Guide!
.._what_will_be_installed:
..contents::
:local:
Basics / What Will Be Installed
```````````````````````````````
Prerequisites
--------------
Ansible by default manages machines over the SSH protocol.
Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running. You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point. When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
.._what_version:
What Version To Pick?
`````````````````````
Because it runs so easily from source and does not require any installation of software on remote
machines, many users will actually track the development version.
Ansible's release cycles are usually about four months long. Due to this short release cycle,
minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch.
Major bugs will still have maintenance releases when needed, though these are infrequent.
If you are wishing to run the latest released version of Ansible and you are running Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu, we recommend using the OS package manager.
For other installation options, we recommend installing via ``pip``, which is the Python package manager.
If you wish to track the development release to use and test the latest features, we will share
information about running from source. It's not necessary to install the program to run from source.
You install Ansible on a control node, which then uses SSH (by default) to communicate with your managed nodes (those end devices you want to automate).
.._control_node_requirements:
Control Node Requirements
````````````````````````````
Currently Ansible can be run from any machine with Python 2 (version 2.7) or Python 3 (versions 3.5 and higher) installed. Windows is not supported for the control node.
Control node requirements
^^^^^^^^^^^^^^^^^^^^^^^^^
Currently Ansible can be run from any machine with Python 2 (version 2.7) or Python 3 (versions 3.5 and higher) installed.
This includes Red Hat, Debian, CentOS, macOS, any of the BSDs, and so on.
Windows is not supported for the control node.
When choosing a control node, bear in mind that any management system benefits from being run near the machines being managed. If you are running Ansible in a cloud, consider running it from a machine inside that cloud. In most cases this will work better than on the open Internet.
@ -54,16 +35,16 @@ When choosing a control node, bear in mind that any management system benefits f
..warning::
Please note that some modules and plugins have additional requirements. For modules these need to be satisfied on the 'target' machine and should be listed in the module specific docs.
Please note that some modules and plugins have additional requirements. For modules these need to be satisfied on the 'target' machine (the managed node) and should be listed in the module specific docs.
.._managed_node_requirements:
Managed Node Requirements
`````````````````````````
Managed node requirements
^^^^^^^^^^^^^^^^^^^^^^^^^
On the managed nodes, you need a way to communicate, which is normally ssh. By
default this uses sftp. If that's not available, you can switch to scp in
:file:`ansible.cfg`. You also need Python 2 (version 2.6 or later) or Python 3 (version 3.5 or
On the managed nodes, you need a way to communicate, which is normally SSH. By
default this uses SFTP. If that's not available, you can switch to SCP in
:ref:`ansible.cfg <ansible_configuration_settings>`. You also need Python 2 (version 2.6 or later) or Python 3 (version 3.5 or
later).
..note::
@ -73,7 +54,7 @@ later).
can use the :ref:`yum module<yum_module>` or :ref:`dnf module<dnf_module>` in Ansible to install this package on remote systems
that do not have it.
* By default, Ansible uses the python interpreter located at :file:`/usr/bin/python` to run its
* By default, Ansible uses the Python interpreter located at :file:`/usr/bin/python` to run its
modules. However, some Linux distributions may only have a Python 3 interpreter installed to
:file:`/usr/bin/python3` by default. On those systems, you may see an error like::
@ -88,20 +69,37 @@ later).
on a client side install of Python to run. Technically, you can use Ansible to install a compatible
version of Python using the :ref:`raw module<raw_module>`, which then allows you to use everything else.
For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it
via
as follows:
..code-block:: shell
$ ansible myhost --become -m raw -a "yum install -y python2"
.._installing_the_control_node:
.._what_version:
Selecting an Ansible version to install
---------------------------------------
Which Ansible version to install is based on your particular needs. You can choose any of the following ways to install Ansible:
* Install the latest release with your OS package manager (for Red Hat Enterprise Linux (TM), CentOS, Fedora, Debian, or Ubuntu).
* Install with ``pip`` (the Python package manager).
* Install from source to access the development (``devel``) version to use and test the latest features.
Installing the Control Node
``````````````````````````````
Because Ansible runs so easily from source and does not require any installation of software on remote
machines, many users will actually track the development version.
Ansible creates new releases two to three times a year. Due to this short release cycle,
minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch.
Major bugs will still have maintenance releases when needed, though these are infrequent.
.._installing_the_control_node:
.._from_yum:
Latest Release via DNF or Yum
+++++++++++++++++++++++++++++
Installing Ansible on RHEL, CentOS, or Fedora
----------------------------------------------
On Fedora:
@ -144,12 +142,12 @@ You can also build an RPM yourself. From the root of a checkout or tarball, use
.._from_apt:
Latest Releases via Apt (Ubuntu)
++++++++++++++++++++++++++++++++
Installing Ansible on Ubuntu
----------------------------
Ubuntu builds are available `in a PPA here <https://launchpad.net/~ansible/+archive/ubuntu/ansible>`_.
To configure the PPA on your machine and install ansible run these commands:
To configure the PPA on your machine and install Ansible run these commands:
..code-block:: bash
@ -166,10 +164,10 @@ Debian/Ubuntu packages can also be built from the source checkout, run:
$ make deb
You may also wish to run from source to get the latest, which is covered below.
You may also wish to run from source to get the development branch, which is covered below.
Latest Releases via Apt (Debian)
++++++++++++++++++++++++++++++++
Installing Ansible on Debian
----------------------------
Debian users may leverage the same source as the Ubuntu PPA.
@ -189,21 +187,21 @@ Then run these commands:
..note:: This method has been verified with the Trusty sources in Debian Jessie and Stretch but may not be supported in earlier versions. You may want to use ``apt-get`` instead of ``apt`` in older versions.
Latest Releases via Portage (Gentoo)
++++++++++++++++++++++++++++++++++++
Installing Ansible on Gentoo with portage
-----------------------------------------
..code-block:: bash
$ emerge -av app-admin/ansible
To install the newest version, you may need to unmask the ansible package prior to emerging:
To install the newest version, you may need to unmask the Ansible package prior to emerging:
Though Ansible works with both Python 2 and 3 versions, FreeBSD has different packages for each Python version.
So to install you can use:
@ -235,17 +233,17 @@ Older versions of FreeBSD worked with something like this (substitute for your c
.._on_macos:
Latest Releases on macOS
++++++++++++++++++++++++++
Installing Ansible on macOS
---------------------------
The preferred way to install Ansible on a Mac is via``pip``.
The preferred way to install Ansible on a Mac is with``pip``.
The instructions can be found in `Latest Releases via Pip`_ section. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely.
The instructions can be found in :ref:`from_pip`. If you are running macOS version 10.12 or older, then you should upgrade to the latest ``pip`` to connect to the Python Package Index securely.
.._from_pkgutil:
Latest Releases via OpenCSW (Solaris)
+++++++++++++++++++++++++++++++++++++
Installing Ansible on Solaris
-----------------------------
Ansible is available for Solaris as `SysV package from OpenCSW <https://www.opencsw.org/packages/ansible/>`_.
@ -256,8 +254,8 @@ Ansible is available for Solaris as `SysV package from OpenCSW <https://www.open
.._from_pacman:
Latest Releases via Pacman (Arch Linux)
+++++++++++++++++++++++++++++++++++++++
Installing Ansible on Arch Linux
---------------------------------
Ansible is available in the Community repository::
@ -269,8 +267,8 @@ Also see the `Ansible <https://wiki.archlinux.org/index.php/Ansible>`_ page on t
.._from_sbopkg:
Latest Releases via sbopkg (Slackware Linux)
++++++++++++++++++++++++++++++++++++++++++++
Installing Ansible on Slackware Linux
-------------------------------------
Ansible build script is available in the `SlackBuilds.org <https://slackbuilds.org/apps/ansible/>`_ repository.
Can be built and installed using `sbopkg <https://sbopkg.org/>`_.
@ -279,14 +277,14 @@ Create queue with Ansible and all dependencies::
# sqg -p ansible
Build and install packages from created queuefile (answer Q for question if sbopkg should use queue or package)::
Build and install packages from a created queuefile (answer Q for question if sbopkg should use queue or package)::
# sbopkg -k -i ansible
.._from swupd:
Latest Release via swupd (Clear Linux)
+++++++++++++++++++++++++++++++++++++++
Installing Ansible on Clear Linux
---------------------------------
Ansible and its dependencies are available as part of the sysadmin host management bundle::
@ -298,10 +296,10 @@ Update of the software will be managed by the swupd tool::
.._from_pip:
Latest Releases via Pip
+++++++++++++++++++++++
Installing Ansible with ``pip``
--------------------------------
Ansible can be installed via``pip``, the Python package manager. If ``pip`` isn't already available on your system of Python, run the following commands to install it::
Ansible can be installed with``pip``, the Python package manager. If ``pip`` isn't already available on your system of Python, run the following commands to install it::
@ -343,22 +341,12 @@ If you wish to install Ansible globally, run the following commands::
Please make sure you have the latest version of ``pip`` before installing Ansible.
If you have an older version of ``pip`` installed, you can upgrade by following `pip's upgrade instructions <https://pip.pypa.io/en/stable/installing/#upgrading-pip>`_ .
.._tagged_releases:
Tarballs of Tagged Releases
+++++++++++++++++++++++++++
Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout? Tarballs of releases are available on the `Ansible downloads <https://releases.ansible.com/ansible>`_ page.
These releases are also tagged in the `git repository <https://github.com/ansible/ansible/releases>`_ with the release version.
.._from_source:
Running From Source
+++++++++++++++++++
Running Ansible from source (devel)
-----------------------------------
Ansible 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
@ -370,7 +358,7 @@ open source projects.
..note::
If you are want to use Ansible Tower as the Control Node, do not use a source installation of Ansible. Please use an OS package manager (like ``apt`` or ``yum``) or ``pip`` to install a stable version.
If you want to use Ansible Tower as the control node, do not use a source installation of Ansible. Please use an OS package manager (like ``apt`` or ``yum``) or ``pip`` to install a stable version.
To install from source, clone the Ansible git repository:
@ -407,7 +395,7 @@ Ansible also uses the following Python modules that need to be installed [1]_:
$ pip install --user -r ./requirements.txt
To update ansible checkouts, use pull-with-rebase so any local changes are replayed.
To update Ansible checkouts, use pull-with-rebase so any local changes are replayed.
..code-block:: bash
@ -427,7 +415,7 @@ other than ``/etc/ansible/hosts``:
$ echo "127.0.0.1" > ~/ansible_hosts
$ export ANSIBLE_INVENTORY=~/ansible_hosts
You can read more about the inventory file in later parts of the manual.
You can read more about the inventory file at :ref:`inventory`.
Now let's test things with a ping command:
@ -437,23 +425,30 @@ Now let's test things with a ping command:
You can also use "sudo make install".
.._shell_completion:
.._tagged_releases:
Finding tarballs of tagged releases
-----------------------------------
Shell Completion
````````````````
Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout? Tarballs of releases are available on the `Ansible downloads <https://releases.ansible.com/ansible>`_ page.
As of Ansible 2.9 shell completion of the ansible command line utilities is available and provided through an optional dependency
called ``argcomplete``. ``argcomplete`` supports bash, and limited support for zsh and tcsh
These releases are also tagged in the `git repository <https://github.com/ansible/ansible/releases>`_ with the release version.
``python-argcomplete`` can be installed from EPEL on Red Hat Enterprise based distributions, and is available in the standard OS repositories for many other distributions.
For more information about installing and configuration see the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>_`.
.._shell_completion:
Installing
++++++++++
Ansible command shell completion
--------------------------------
via yum/dnf
-----------
As of Ansible 2.9, shell completion of the Ansible command line utilities is available and provided through an optional dependency
called ``argcomplete``. ``argcomplete`` supports bash, and has limited support for zsh and tcsh.
You can install ``python-argcomplete`` from EPEL on Red Hat Enterprise based distributions, and or from the standard OS repositories for many other distributions.
For more information about installing and configuration see the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>`_.
Installing ``argcomplete`` on RHEL, CentOS, or Fedora
Sandra McCann
5 years ago
committed by