How To Install and Configure Ansible on Ubuntu

Ansible is an open-source automation tool that lets you manage and configure servers from a single control node without installing agent software on the machines you manage. Unlike tools such as Chef or Puppet, Ansible connects over SSH and uses human-readable YAML files to define automation tasks. This agentless approach makes it one of the most widely adopted configuration management tools in production Linux environments.

In this tutorial, you will install and configure Ansible on an Ubuntu server, set up an inventory of managed hosts, verify connectivity, run ad-hoc commands, and write your first playbook. You will also learn about the different installation methods available, including the Ansible PPA, the default Ubuntu repository, and pipx, so you can choose the approach that fits your environment.

For a broader overview of how Ansible fits into configuration management workflows, see An Introduction to Configuration Management with Ansible.

• Ansible only needs to be installed on the control node. Managed nodes require Python 3 and SSH access, but no Ansible software.
• The Ansible PPA (ppa:ansible/ansible) provides the latest stable release and is the recommended installation method for most production setups.
• You can also install Ansible using pipx for isolated, user-level installations, or from the default Ubuntu repository for a simpler setup with an older version.
• The inventory file defines which hosts Ansible manages. You can use the default file at /etc/ansible/hosts or create project-specific inventory files.
• Always test connectivity with ansible all -m ping after configuring your inventory and SSH keys before running any automation.

To follow this tutorial, you will need:

• One Ansible control node: The Ansible control node is the machine you will use to connect to and control the Ansible hosts over SSH. Your Ansible control node can be your local machine or a dedicated server running Ansible. This guide assumes your control node is an Ubuntu 22.04 or 24.04 system. Make sure the control node has:

  • A non-root user with sudo privileges. To set this up, follow Steps 2 and 3 of the Initial Server Setup Guide for Ubuntu. If you are using a remote server as your Ansible control node, follow every step of that guide to configure a firewall with ufw and enable external access to your non-root user profile.
  • An SSH key pair associated with this user. To set this up, follow Step 1 of How to Set Up SSH Keys on Ubuntu.

• One or more Ansible hosts (managed nodes): An Ansible host is any machine that your Ansible control node is configured to automate. This guide assumes your Ansible hosts are remote Ubuntu servers. Make sure each Ansible host has:

  • The Ansible control node’s SSH public key added to the authorized_keys of a system user. This user can be either root or a regular user with sudo privileges. To set this up, follow Step 2 of How to Set Up SSH Keys on Ubuntu 22.04.

Before installing Ansible, it helps to understand the three main installation methods available on Ubuntu. Each method has tradeoffs in terms of version freshness, ease of maintenance, and isolation.

Recommended method for production environments

For production use, install Ansible from the official Ansible PPA. This gives you the latest stable release with regular updates through apt upgrade. The PPA is maintained by the Ansible project and supports Ubuntu 22.04 and 24.04.

Recommended method for development or testing environments

For development or testing, pipx installs Ansible in an isolated Python virtual environment. This avoids conflicts with system-level Python packages and lets you run multiple Ansible versions side by side. The official Ansible documentation now includes pipx as a supported installation method, partly in response to Python PEP 668 restrictions on system-wide pip installs in newer Ubuntu releases.

The Ansible PPA provides the most recent stable release of the Ansible community package. This is the recommended method for most users.

Adding the Ansible PPA to your system

First, install the software-properties-common package if it is not already present. This package provides the apt-add-repository command:

sudo apt update
sudo apt install software-properties-common

Next, add the official Ansible PPA to your system’s list of sources:

sudo apt-add-repository ppa:ansible/ansible

Press ENTER when prompted to accept the PPA addition.

Updating the package index and installing Ansible

Refresh your system’s package index so that it includes the packages available in the newly added PPA, then install Ansible:

sudo apt update
sudo apt install ansible

Verifying the installed Ansible version

Confirm the installation by checking the Ansible version:

ansible --version

You will see output similar to the following:

Output
ansible [core 2.17.x]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/sammy/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3/dist-packages/ansible
  ansible collection location = /home/sammy/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.10.12 (main, ...) [GCC 11.4.0]
  jinja version = 3.0.3
  libyaml = True

The exact version numbers will depend on when you install the package. The important detail is that the output confirms Ansible is installed and shows the Python version it is using.

If you prefer a simpler setup and do not need the latest version, you can install Ansible directly from the default Ubuntu repository without adding any PPAs.

sudo apt update
sudo apt install ansible

The version available through the default repository depends on your Ubuntu release. Ubuntu 22.04 ships with Ansible 2.10.x in its repos, while Ubuntu 24.04 includes a newer version. This approach requires fewer steps but may lag behind the latest features and bug fixes in the Ansible project.

To check which version is available before installing:

apt-cache policy ansible

If you need a more current version, use the PPA method from Step 1 or the pipx method from Step 3.

The pipx tool installs Python applications in isolated virtual environments. This keeps Ansible and its dependencies separate from your system Python packages.

Installing pipx on Ubuntu

On Ubuntu 22.04 and 24.04, install pipx with:

sudo apt update
sudo apt install pipx

After installing, make sure ~/.local/bin is on your PATH. Run:

pipx ensurepath

Close and reopen your terminal, or run source ~/.bashrc (or source ~/.zshrc if you use Zsh) for the PATH change to take effect.

Installing Ansible into an isolated pipx environment

Install the full Ansible community package with:

pipx install --include-deps ansible

The --include-deps flag is required because the ansible package depends on ansible-core and other supporting libraries.

To install only the minimal ansible-core package instead:

pipx install ansible-core

Verify the installation:

ansible --version

When to prefer this method

Use pipx when you need to:

• Keep Ansible isolated from other Python packages on your system
• Install a specific version of Ansible alongside other versions
• Work on a system where pip install is restricted by PEP 668 (common on Ubuntu 24.04 and later)
• Test playbooks against different Ansible versions

The inventory file tells Ansible which hosts it should manage. You can include one to hundreds of servers, organized into groups and subgroups. The inventory file is also used to set variables that apply to specific hosts or groups, such as the Python interpreter path or SSH connection parameters.

Understanding the default inventory file location

Ansible creates a default inventory file at /etc/ansible/hosts when installed through the PPA or apt. Open this file to edit it:

sudo nano /etc/ansible/hosts

Grouping hosts and setting host variables

The following example defines a group named [servers] with three hosts, each identified by a custom alias. Replace the highlighted IP addresses with the actual IP addresses of your managed nodes:

[servers]
server1 ansible_host=203.0.113.111
server2 ansible_host=203.0.113.112
server3 ansible_host=203.0.113.113

[all:vars]
ansible_python_interpreter=/usr/bin/python3

The [all:vars] section sets the ansible_python_interpreter variable for every host in the inventory. This tells Ansible to use /usr/bin/python3 on the remote servers. Python 3 is the default on Ubuntu 22.04 and 24.04, but setting this variable explicitly prevents warnings about Python interpreter discovery.

When you are finished, save and close the file by pressing CTRL+X, then Y, and ENTER to confirm your changes.

Verifying your inventory

To verify that Ansible can parse your inventory file correctly, run:

ansible-inventory --list -y

You will see output similar to this:

Output
all:
  children:
    servers:
      hosts:
        server1:
          ansible_host: 203.0.113.111
          ansible_python_interpreter: /usr/bin/python3
        server2:
          ansible_host: 203.0.113.112
          ansible_python_interpreter: /usr/bin/python3
        server3:
          ansible_host: 203.0.113.113
          ansible_python_interpreter: /usr/bin/python3
    ungrouped: {}

If the output reflects the hosts and variables you configured, your inventory is set up correctly.

Ansible uses SSH to communicate with managed nodes. Before running any Ansible commands, make sure your control node can reach each managed node over SSH without a password prompt.

Generating an SSH key pair on the control node

If you do not already have an SSH key pair on your control node, generate one with:

ssh-keygen -t ed25519 -C "ansible-control-node"

Press ENTER to accept the default file location (~/.ssh/id_ed25519). You can optionally set a passphrase or press ENTER to skip it.

Copying the public key to each managed node

Use ssh-copy-id to copy your public key to each managed node. Replace root with your remote username and 203.0.113.111 with the managed node’s IP address:

ssh-copy-id root@203.0.113.111

Repeat this command for each managed node listed in your inventory.

Testing SSH connectivity manually

Before running Ansible, verify that you can SSH into each managed node without being prompted for a password:

ssh root@203.0.113.111

If you connect successfully, type exit to return to your control node. If you see a password prompt or an error, review your SSH key configuration before proceeding.

After configuring your inventory and SSH keys, verify that Ansible can communicate with all your managed nodes.

Running the ping module against your inventory

From your control node, run:

ansible all -m ping -u root

This command uses Ansible’s built-in ping module to test connectivity to every host in your inventory. The -u root flag specifies the remote user. If your hosts have a regular sudo user, replace root with that username.

The ping module tests whether:

• Each host is reachable over the network
• Your SSH credentials are valid
• The remote host can run Ansible modules using Python

Interpreting a successful response

A successful response looks like this:

Output
server1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
server2 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
server3 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

A "pong" reply from a host confirms that Ansible can authenticate and execute modules on that server.

If this is the first time connecting to these servers via SSH, you will be asked to confirm the host key fingerprint. Type yes and press ENTER for each host.

Interpreting and resolving common failure outputs

If a host returns UNREACHABLE, check that:

• The host’s IP address in your inventory is correct
• SSH is running on the managed node
• Your SSH key has been copied to the managed node
• No firewall rules are blocking port 22

For additional connection troubleshooting options, see the Ansible Cheat Sheet Guide.

Ad-hoc commands let you run a single task on one or more managed nodes without writing a playbook. They are useful for quick, one-off operations like checking disk space, restarting a service, or installing a package.

Syntax of an ad-hoc command

The general syntax of an ad-hoc Ansible command is:

ansible host-pattern -m module -a "module arguments" -u remote_user

• host-pattern: The hosts to target (all, a group name, or specific host aliases)
• -m: The Ansible module to use
• -a: Arguments to pass to the module
• -u: The remote user to connect as

Checking disk usage across all managed nodes

To check disk usage on all servers in your inventory:

ansible all -a "df -h" -u root

Output
server1 | CHANGED | rc=0 >>
Filesystem      Size  Used Avail Use% Mounted on
udev            3.9G     0  3.9G   0% /dev
tmpfs           798M  624K  798M   1% /run
/dev/vda1       155G  2.3G  153G   2% /
tmpfs           3.9G     0  3.9G   0% /dev/shm
tmpfs           5.0M     0  5.0M   0% /run/lock
/dev/vda15      105M  3.6M  101M   4% /boot/efi
tmpfs           798M     0  798M   0% /run/user/0

...

When you do not specify a module with -m, Ansible defaults to the command module, which runs the given shell command on each host.

Checking uptime and gathering system facts

To check the uptime of every host in the servers group:

ansible servers -a "uptime" -u root

To install a package using the apt module:

ansible all -m apt -a "name=vim state=latest" -u root

You can target individual hosts or multiple hosts separated by colons:

ansible server1:server2 -m ping -u root

For more examples and patterns, see How to Manage Multiple Servers with Ansible Ad Hoc Commands.

Playbooks are YAML files that define a set of tasks to execute on your managed nodes. While ad-hoc commands work for quick tasks, playbooks let you define repeatable, version-controlled automation workflows.

Playbook YAML structure and syntax basics

A playbook consists of one or more plays. Each play specifies:

• hosts: Which managed nodes to target
• become: Whether to run tasks with elevated privileges (sudo)
• tasks: An ordered list of actions to perform

A simple playbook to update apt packages on managed nodes

Create a new directory for your playbooks, then create a playbook file:

mkdir ~/ansible-practice
nano ~/ansible-practice/update-apt.yml

Add the following content:

---
- hosts: all
  become: true
  tasks:
    - name: Update apt package cache
      apt:
        update_cache: yes

    - name: Upgrade all packages to the latest version
      apt:
        upgrade: dist

    - name: Remove unused dependencies
      apt:
        autoremove: yes

This playbook connects to all hosts in your inventory, runs commands with sudo (become: true), updates the apt cache, upgrades all packages, and removes unused dependencies.

Running the playbook

Run the playbook with the ansible-playbook command:

ansible-playbook ~/ansible-practice/update-apt.yml -u root

If you are using a non-root user with sudo privileges, add --ask-become-pass to be prompted for the sudo password:

ansible-playbook ~/ansible-practice/update-apt.yml -u sammy --ask-become-pass

Interpreting playbook output

The output shows the status of each task:

Output
PLAY [all] *********************************************************************

TASK [Gathering Facts] *********************************************************
ok: [server1]
ok: [server2]
ok: [server3]

TASK [Update apt package cache] ************************************************
changed: [server1]
changed: [server2]
changed: [server3]

TASK [Upgrade all packages to the latest version] ******************************
changed: [server1]
changed: [server2]
changed: [server3]

TASK [Remove unused dependencies] **********************************************
ok: [server1]
ok: [server2]
ok: [server3]

PLAY RECAP *********************************************************************
server1                    : ok=4    changed=2    unreachable=0    failed=0    skipped=0
server2                    : ok=4    changed=2    unreachable=0    failed=0    skipped=0
server3                    : ok=4    changed=2    unreachable=0    failed=0    skipped=0

• ok means the task ran successfully and the system was already in the desired state.
• changed means the task made a modification to the system.
• failed means the task encountered an error.

For more on writing playbooks, see the How to Write Ansible Playbooks series.

Upgrading Ansible

If you installed Ansible via the PPA or default repository, upgrade it alongside your other system packages:

sudo apt update
sudo apt upgrade ansible

If you installed Ansible via pipx, upgrade with:

pipx upgrade ansible

After upgrading, verify the new version:

ansible --version

Removing Ansible

To remove Ansible installed via apt:

sudo apt remove ansible
sudo apt autoremove

To remove Ansible installed via pipx:

pipx uninstall ansible

SSH host key verification failed

If you see an error like Host key verification failed, the SSH fingerprint of the managed node has changed or has not been accepted yet. You can resolve this by connecting to the host manually with SSH to accept the fingerprint:

ssh root@203.0.113.111

Type yes when prompted to add the host to your known hosts file.

To skip host key checking for all Ansible connections (not recommended in production), add this to your ansible.cfg or set the environment variable:

export ANSIBLE_HOST_KEY_CHECKING=False

Python interpreter not found on managed node

If Ansible reports MODULE FAILURE with a message about the Python interpreter, the managed node may not have Python 3 installed. Install it with:

ssh root@203.0.113.111 "apt update && apt install python3 -y"

Also make sure the ansible_python_interpreter variable in your inventory is set to /usr/bin/python3.

Permission denied when connecting to managed node

A Permission denied (publickey) error typically means your SSH key has not been copied to the managed node. Run ssh-copy-id again:

ssh-copy-id root@203.0.113.111

If you are connecting as a non-root user, make sure that user exists on the managed node and has your public key in their ~/.ssh/authorized_keys file.

Inventory host not reachable

If ansible all -m ping returns UNREACHABLE for a host, verify:

1. The IP address in your inventory file is correct
2. The managed node is powered on and connected to the network
3. SSH is running on the managed node: sudo systemctl status ssh
4. No firewall is blocking port 22 on the managed node: sudo ufw status

1. What is the difference between installing Ansible via apt and via the Ansible PPA on Ubuntu?

The default Ubuntu apt repository ships the Ansible version that was current when the Ubuntu release was packaged. This version does not get major updates, only security patches. The official Ansible PPA (ppa:ansible/ansible) provides the latest stable release from the Ansible project, giving you access to newer modules, bug fixes, and performance improvements. For most production setups, the PPA method is the better choice.

2. Does Ansible need to be installed on managed nodes?

No. Ansible follows an agentless architecture. You only install Ansible on the control node. Managed nodes need Python 3 (which ships by default on Ubuntu 22.04 and 24.04) and an SSH server running. Ansible pushes modules to managed nodes over SSH, executes them, and then removes them.

3. Can I install Ansible on Ubuntu without root privileges?

Yes. Using pipx install --include-deps ansible installs Ansible in a user-level virtual environment without requiring sudo. This approach is well-suited for development environments or situations where you do not have administrative access to the system.

4. How do I verify that Ansible is correctly installed on Ubuntu?

Run ansible --version in your terminal. The output displays the installed Ansible version, the Python version it is using, the configuration file path, and the module search paths. If the command is not found, Ansible is either not installed or not on your system’s PATH.

5. Is Ansible on Ubuntu 22.04 compatible with Ubuntu 24.04 managed nodes?

Yes. Ansible is cross-version compatible for standard modules. A control node running Ubuntu 22.04 can manage nodes running Ubuntu 24.04, and vice versa, as long as Python 3 and SSH are available on the managed nodes. Ansible communicates over SSH and does not depend on the managed node’s OS version matching the control node.

In this tutorial, you installed Ansible on Ubuntu using the PPA method, configured an inventory file with managed hosts, set up SSH key-based authentication, tested connectivity with the ping module, ran ad-hoc commands, and created your first playbook. You also learned about alternative installation methods using pipx and the default Ubuntu repository, and reviewed common troubleshooting steps for SSH and connectivity issues.

Ansible provides a foundation for automating server provisioning, application deployment, and ongoing configuration management across your infrastructure. With the control node configured and your inventory in place, you can start building more complex playbooks to automate routine tasks across all your servers.

To continue building on what you have learned, explore these resources:

• How to Use Ansible to Automate Initial Server Setup on Ubuntu covers automating your standard server setup process, including creating users, configuring firewalls, and hardening SSH.
• How to Write Ansible Playbooks is an 11-part series that walks through tasks, variables, templates, handlers, and roles in depth.
• How to Manage Multiple Servers with Ansible Ad Hoc Commands covers advanced patterns for running one-off tasks across server groups.
• How to Use Ansible to Install and Set Up Docker on Ubuntu demonstrates a practical playbook for deploying Docker containers.
• The Ansible Cheat Sheet Guide provides a quick reference for common Ansible commands and options.

If you are looking to provision and manage Ubuntu servers at scale, DigitalOcean Droplets provide a fast way to deploy cloud servers that you can configure and automate with Ansible. You can also use the DigitalOcean API together with Ansible’s community.digitalocean collection to create and manage Droplets, firewalls, load balancers, and other infrastructure resources directly from your playbooks.