Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 29 ยท Getting Started

Installing Ansible and Your First Ping

Install Ansible with pip, pipx or a package manager, learn ansible-core versus ansible, set up a lab host, and run your first ping against localhost and SSH.

Installing Ansible takes one command, but there are several ways to do it and a few choices that confuse beginners: which package, which Python, and where do you try it out? This lesson walks through the options, shows how to check your install, and ends with the traditional first success: a green pong from a machine you control.

Everything here happens on the control node, the machine you work from (see What Is Ansible?). The commands are read-only examples in this tutorial; you run them in your own terminal. After the install steps, small JavaScript stand-ins show what the ping module returns and how the ansible command line is read.

ansible-core versus ansible

Two packages share the name, and the difference matters:

Package What it contains
ansible-core The engine: the ansible and ansible-playbook commands, plus the built-in modules in the ansible.builtin collection
ansible ansible-core plus a large curated set of community and vendor collections (cloud, network, Docker, databases and more)

If you are learning, install ansible: it works out of the box with the examples you will find online. If you want a small, controlled install (for example in a CI image) install ansible-core and add only the collections you need. Collections are covered in Collections, Galaxy and Reusable Content.

Ways to install

Ansible is a Python application, so the control node needs a reasonably recent Python 3. Pick one method.

pipx (recommended for most people). pipx installs a Python program in its own isolated environment and puts the commands on your PATH:

Terminal
pipx install --include-deps ansible

--include-deps is needed because the commands (ansible-playbook, ansible-vault and the others) come from a dependency of the ansible package.

pip in a virtual environment. Good when a project pins its own version:

Terminal
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ansible

Using a virtual environment keeps Ansible away from the system Python, which avoids version clashes with your operating system's own tools.

Your system's package manager. Convenient, but the version is often older:

Terminal
# Debian / Ubuntu
sudo apt update && sudo apt install ansible

# Fedora
sudo dnf install ansible

# macOS with Homebrew
brew install ansible

For anything you share with a team or run in CI, pin the version (pip install "ansible==<version>") in a requirements.txt. Ansible changes behavior between releases, and a pinned version makes runs reproducible.

Windows users: use WSL

Ansible does not run as a control node natively on Windows. The usual answer is the Windows Subsystem for Linux: install a distribution such as Ubuntu with wsl --install, open its terminal and follow the Linux steps above. Windows machines can still be managed nodes (over WinRM or SSH); that is covered in Windows, Network Devices and Cloud Modules.

Check the install

Terminal
ansible --version

The first line shows the engine version, for example ansible [core 2.xx.y]. Below it you see the config file in use (often None until you create one), the Python version Ansible runs on and the paths where it looks for modules and collections. Your numbers will differ from any tutorial; what matters is that the command runs.

Terminal
ansible-playbook --version
ansible-doc --version

All the Ansible commands come from the same install, so they report the same core version.

Your first ping: localhost

The ping module is not the network ping command. It connects to the host, checks that Ansible can run a Python module there, and returns pong. That makes it the best "is everything wired up?" test.

Terminal
ansible localhost -m ping

Expected output:

TEXT
localhost | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Newer versions may also print an ansible_facts block with the path of the Python interpreter they found. That is normal. Here is how to read the line: localhost is the host, SUCCESS is the status, and the JSON after => is the module's result. "changed": false says the module changed nothing, as expected for a read-only check.

Localhost works without an inventory because Ansible has an implicit entry for it that uses a local connection instead of SSH. That proves the install, but not SSH.

A lab host to practice on

To practice, you want a machine you may break. Good options:

  • a spare Linux machine or a virtual machine (VirtualBox, a cloud VM, a Raspberry Pi);
  • a container with an SSH server, which starts in seconds and is thrown away afterwards;
  • a WSL distribution on a different port.

For a container lab, any image that runs sshd and has Python works. Publish its SSH port on your machine, for example 2222, and make sure your public key is allowed in. You then describe the host in a small inventory file:

INI
# hosts.ini
[lab]
lab1 ansible_host=127.0.0.1 ansible_port=2222 ansible_user=root

Then ping it:

Terminal
ansible lab -i hosts.ini -m ping
TEXT
lab1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

If you log in with a password instead of a key, add -k (ask for the SSH password); that needs the sshpass program on the control node. Keys are better, and you will set them up properly in SSH, Privilege Escalation and Hardening.

When ping fails

Two failures are common, and the output tells you which:

TEXT
lab1 | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ...",
    "unreachable": true
}

UNREACHABLE means Ansible could not even log in: wrong address or port, no key, a firewall, or a host key problem. Test with a plain ssh first.

TEXT
lab1 | FAILED! => {
    "changed": false,
    "module_stderr": "...",
    "msg": "MODULE FAILURE"
}

FAILED means the login worked but the module could not run, most often because the managed node has no usable Python. Installing Python on the target fixes it. The distinction (unreachable versus failed) is useful for the rest of the course.

flowchart TD
    A["ansible lab -m ping"] --> B{"SSH login works?"}
    B -- no --> U["UNREACHABLE"]
    B -- yes --> C{"Module runs<br/>(Python present)?"}
    C -- no --> F["FAILED"]
    C -- yes --> S["SUCCESS: pong"]

The three possible outcomes of a ping, in the order Ansible reaches them.

A stand-in for the ping module

The module itself is only a few lines of Python that returns a dictionary. This stand-in imitates it, including the way Ansible prints the result and the two failure shapes. It does not use SSH; the "network" is a table of hosts.

JS Imitating the ping module's result

Press Run (or Ctrl + Enter) to see the console output here.

No output.

You can see the same three outcomes as the real command: success with a JSON result, UNREACHABLE when nothing answers, and FAILED when the module cannot run. The real ping module also accepts a data argument (default pong), and data=crash makes it raise an exception on purpose, which is a handy way to see what a module failure looks like.

Reading the command line

Every ad-hoc call has the same shape: ansible <pattern> -i <inventory> -m <module> -a "<arguments>". The next stand-in splits a command line into those parts so the structure is clear. Real Ansible uses Python's argparse for this; the idea is the same.

JS Splitting an ansible command line

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the module defaults to command when you leave out -m, which is how the real tool behaves too. The next lessons build on this: Inventory: Hosts and Groups explains the file you pass with -i, and Ad-Hoc Commands uses many more modules.

A short checklist for a working setup

  1. ansible --version prints a version.
  2. ansible localhost -m ping prints pong.
  3. You have a lab host you can SSH into with a key.
  4. ansible lab -i hosts.ini -m ping prints pong.

If all four pass, you are ready for everything else in the tutorial.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main difference between the ansible-core and ansible packages?

    ansible-core is the engine with the ansible.builtin modules. The ansible package bundles it with many community and vendor collections.
  2. 2. You are on Windows and want to run playbooks from your own machine. What is the usual approach?

    Windows is not supported as a control node, so you use WSL (or a VM, container or CI runner). Windows hosts can still be managed nodes.
  3. 3. What does ansible localhost -m ping verify?

    The ping module is not ICMP. It runs a small module and returns pong. Against localhost it uses a local connection, so it does not test SSH.
  4. 4. A ping returns UNREACHABLE. Where should you look first?

    UNREACHABLE means Ansible could not connect or log in. FAILED, by contrast, means the connection worked but the module failed, often for lack of Python.
  5. 5. If you leave out -m on an ad-hoc command, which module runs?

    The default module for the ansible command is command, which runs the program you give with -a without a shell.

Summary

  • Install ansible (with collections) for learning, or ansible-core for a minimal, controlled setup; pipx or a virtual environment keeps it isolated.
  • Pin the version in shared projects, and use WSL on Windows for the control node.
  • ansible --version checks the install, and ansible localhost -m ping proves modules run.
  • The ping module returns {"changed": false, "ping": "pong"}; it is not network ping.
  • UNREACHABLE is a connection problem, FAILED is a module problem.
  • A small SSH-enabled container or VM makes a perfect lab host described in a tiny inventory file.

Next: Inventory: Hosts and Groups