Mastering Ansible Navigator: A Modern CLI for Running and Debugging Playbooks

When you're doing network automation, especially at scale, you need your results to be consistent and repeatable. For years, ansible-playbook was the go-to command, but as Ansible shifted towards using containerized Execution Environments (EEs), particularly within Ansible Automation Platform (AAP), we needed a better command-line tool to match.

That's where Ansible Navigator comes in. It's built specifically to work with Execution Environments, giving you a standard way to run and debug your Ansible playbooks, especially the ones targeting network gear. Let's dive into a TLDR Ansible Navigator tutorial on what Navigator is, how to get it running, configure it, and actually use it.

What is ansible-navigator?

ansible-navigator (also known historically as Ansible content navigator) is a command-line tool and Text-based User Interface (TUI) designed to run and help develop Ansible content by leveraging Execution Environments. Remember, EEs are container images (using Docker or Podman) that bundle up everything needed for your automation: Ansible Core, the right Python version, specific Python libraries (netmiko, napalm, etc.), required Ansible Collections (cisco.ios, arista.eos), and any other system tools.

Instead of you juggling Python virtual environments and collections on your own machine, ansible-navigator runs your playbooks insidethese standardized EEs. This is huge because it means your automation acts the same way whether it's running on your laptop, in a CI/CD pipeline, or on AAP itself. Consistency!

(You can tell Navigator to run without an EE using --ee false, but that kind of defeats the main purpose and puts you back in the business of manually managing dependencies, just like the old ansible-playbook days.)

Why Did We Need Ansible Navigator?

Running ansible-playbook directly on different machines (your laptop, a CI server, production controllers) often led to headaches. You'd hit inconsistencies because of different Python versions, system libraries, or versions of dependencies like paramiko. The old command didn't understand containerized EEs, which are central to AAP. Plus, exploring your inventory, checking documentation, or debugging playbook runs often meant using separate commands and parsing plain text output.

Ansible Navigator fixes these problems:

• Gives you a single CLI tool that understands and uses EEs locally.
• Lets you test consistently using the exact same EEs that AAP would use.
• Offers an interactive TUI that makes it easier to debug, browse docs, check inventory/configs, and review results.
• Bridges the gapbetween local development and how things run on Ansible Automation Platform.

Execution Environments (EEs) Explained

EEs are the foundation here. They are container images packed with:

• A specific ansible-core version.
• A defined Python version and needed libraries (like netaddr, pyats, ncclient, paramiko).
• The Ansible Collections you require (ansible.netcommon, cisco.ios, etc.).
• ansible-runner (the tool Navigator and AAP use under the hood to run ansible-core inside the EE).
• Any OS-level tools needed by your modules (maybe gcc, krb5-devel, network clients), usually installed via the base image's package manager (dnf, apt).

While Red Hat provides basic EEs, you'll almost always end up building custom EEs using ansible-builder to get the exact mix of collections, libraries, and tools your network automation needs.

Read more: For a deeper dive into EEs, you can also refer to our article on Ansible Execution Environments

Comparison: Ansible Playbook vs. ansible-navigator vs. ansible-runner (AAP)

The Role of Private Automation Hub (PAH)

If you're using AAP, you likely have Automation Hub (or an on-prem Private Automation Hub - PAH). This acts as your company's official repository for Collections and EEs.

Navigator integrates nicely with PAH:

• Pulls EEs:You can configure Navigator to grab certified or custom EEs directly from your PAH, ensuring everyone uses the approved environments.
• Pulls Collections:When building EEs with ansible-builder, PAH can be the trusted source for the collections you include.

Using PAH enforces governance and makes sure the EEs you test with locally match what AAP uses in staging/production.

How to Install Ansible Navigator

Ansible Navigator Installation via pip (Good for general use, gets the latest version)

Install via pip

python3 -m pip install --user ansible-navigator

Important Step: Update your PATH! If you installed with --user, the command might end up in a place like ~/.local/bin (Linux) or ~/Library/Python/X.Y/bin (macOS). If you get "command not found", you MUST add this directory to your shell's PATH.

• Linux: Add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc or ~/.zshrc.
• macOS: Add export PATH="$HOME/Library/Python/X.Y/bin:$PATH" (check your Python version) to ~/.zshrc.

Then, reload your shell (source ~/.bashrc) or open a new terminal.

Read more here.

Verify it works:

ansible-navigator --version

Install Ansible Navigator on RHEL 9 (via AAP Repo - Needs Subscription)

This method ensures you install the version of Navigator tested and packaged with a specific Ansible Automation Platform release, but it requires a valid Red Hat subscription.

Attach the appropriate AAP subscription pool

sudo subscription-manager attach --pool=<your-aap-sku-pool-id>

Enable the correct AAP repository for RHEL 9 (e.g., ansible-automation-platform-2.4-for-rhel-9-x86_64-rpms - adjust version as needed):

sudo subscription-manager repos --enable ansible-automation-platform-2.4-for-rhel-9-x86_64-rpms

Install using dnf:

sudo dnf install ansible-navigator

Verify installation:

ansible-navigator --version

While the EPEL repository provides many packages for RHEL, the official Red Hat documentation specifically directs users to the AAP repository for installing ansible-navigator itself. Dependencies might sometimes come from EPEL, but Navigator should be sourced from the AAP repo for proper integration.

Other OS (Ubuntu/Debian, macOS, Windows WSL2)

Install Python 3, pip, and Docker/Podman first using apt or brew. Then use the pip install --user method above, making sure your PATH is set correctly. For Windows, use WSL2, install Linux, and follow the Linux steps inside WSL2.

Read more: Ansible Setup Guide

Configuring ansible-navigator.yml

Ansible Navigator offers extensive configuration options to customize its behavior, define default settings, and streamline workflows. These settings can be managed primarily through the ansible navigator config file.

The configuration file can be written in either YAML or JSON. YAML is generally more common and readable.

Create a ansible-navigator.yml configuration file to define your preferred settings and Execution Environment Ansible Navigator image.

Example ansible-navigator.yml:

---
execution-environment:
  Container-engine: podman
  enabled: true
  image: registry.example.com/ansible/network-ee:latest
  pull:
    policy: missing


mode: stdout
editor:
  command: "vim"

The following table provides a quick reference for common settings:

How to run a playbook with Ansible Navigator?

Simple ansible-navigator run playbook:

ansible-navigator run playbooks/network_ping.yml

Run Ad-hoc Commands (Using exec)

The exec subcommand lets you run any command inside the specified EE. To run an ad-hoc Ansible command:

ansible-navigator exec ansible all -m ping -i inventories/network_inventory.yml

(For simple ad-hoc tasks, just using ansible-navigator run with a small playbook or exploring in interactive mode might be easier).

Using ansible-navigator inventory

Navigator helps you inspect your inventory:

Interactive Mode (-m interactive, default): Launches the TUI. Browse groups, hosts, view variables. Press : for help, Esc to go back.

ansible-navigator inventory -i inventories/network_inventory.yml

Standard Output Mode (-m stdout): Acts like ansible-inventory.

• --list: Dump inventory as JSON.
• --graph: Show group hierarchy.

ansible-navigator inventory -i inventories/network_inventory.yml --list 
ansible-navigator inventory -i inventories/network_inventory.yml --graph

Example Inventory (inventories/network_inventory.yml):

all:
 hosts:
   router1:
     ansible_host: 10.1.1.1
     ansible_network_os: ios
     ansible_user: admin
     ansible_password: password
 children:
   cisco_devices:
     hosts:
       router1:
       switch1:

Run Navigator with Inventory:

ansible-navigator run playbooks/show_version.yml -i inventories/network_inventory.yml

Ansible Navigator Installing and Using Collections

This is key: You don't install collections on your host machine for Navigator (unless using --ee false). Collections belong inside the Execution Environment.

Here's the workflow to use collections:

1 Define Collections Needed: Create a requirements.yml file listing the collections and versions.

collections:
- name: cisco.ios
- name: arista.eos

2 Define the EE: Create execution-environment.yml telling ansible-builder to include these collections (referencing your requirements.yml).

version: 3
dependencies:
 galaxy:
   requirements.yml

3 Build the EE Image: Use ansible-builder.

ansible-builder build -t network-ee -f execution-environment.yml

4 (Recommended) Push to Registry/PAH: Share the image.

podman push network-ee registry.example.com/ansible/network-ee:latest

Read more: For a deeper dive into EEs, you can also refer to our article on Ansible Execution Environments

5 Tell Navigator to Use It: Update ansible-navigator.yml to point to your new custom EE image.

#In ansible-navigator.yml
execution-environment: 
image: registry.example.com/ansible/my-custom-network-ee:latest

Now, when you run ansible-navigator, it pulls and uses your custom EE, which already contains the collections your playbooks need.

Understand how to optimize your automation deployments with execution strategies.

Real-World Network Automation Examples

Use Case: Get Interface Details

playbooks/get_interfaces.yml:

- name: Get Cisco Interfaces
hosts: cisco_devices
gather_facts: no
tasks:
   - name: Gather interface facts
     cisco.ios.ios_interfaces:
       config: false
     register: intf_output

   - name: Display interface facts
     debug:
       var: intf_output

Run it:

ansible-navigator run playbooks/get_interfaces.yml -i inventories/network_inventory.yml

Use Case: Configure Interface Description

playbooks/configure_interface.yml:

- name: Configure Network Interfaces
  hosts: cisco_devices
  gather_facts: no
  tasks:
    - name: Configure interface description
      cisco.ios.ios_interfaces:
        config:
          - name: GigabitEthernet0/0
            description: "Configured by Ansible Navigator"
      register: result

Run:

ansible-navigator run playbooks/configure_interface.yml

Use Case: Check NTP Compliance

playbooks/check_ntp.yml:

- name: Check Network Compliance
  hosts: network_devices
  gather_facts: no
  tasks:
    - name: Gather facts
      ansible.netcommon.cli_command:
        command: show run
      register: config

    - name: Check for compliance
      ansible.builtin.assert:
        that:
          - "'ntp server' in config.stdout"
        fail_msg: "NTP configuration missing"

Run:

ansible-navigator run playbooks/check_ntp.yml

Troubleshooting Ansible Navigator

• ansible-navigator: command not found
  • Likely Cause:Your PATH is wrong (especially after pip install --user).
  • Fix:Find where pip installed it (~/.local/bin? ~/Library/Python/X.Y/bin?). Add that exact directory to your PATH in your shell config file (.bashrc, .zshrc). Reload your shell (source ~/.bashrc) or open a new terminal.
  • Other Causes:Maybe you're in the wrong Python venv? Install error? Running sudo (uses root's PATH)?
• Playbook runs differently in Navigator vs. ansible-playbook
  • Likely Cause:The environment insidethe EE (Ansible version, Python version, library versions, collections) is different from your host OS. This is expectedand why EEs provide consistency.
  • Troubleshooting:Always test using Navigator withthe target EE. Check SSH keys/configs work from withinthe EE. Check file paths in playbooks are valid insidethe EE (use volume mounts if needed).
  • Isolation Test:Run ansible-navigator run playbook.yml --ee false. If it works now (but failed before), the issue is definitely EE-related (missing package, different library version, etc.).

How CloudMyLab Helps with Navigator/EE Workflows

Setting up container engines, grabbing network OS images, building labs – it can be a time sink. CloudMyLab helps by providing ready-to-go infrastructure:

• Ready Network Devices: Access virtual routers/switches/firewalls instantly. No local emulation setup needed.
• Pre-configured Control Nodes: Use VMs already set up with Podman/Docker, ready for Navigator and EE builds.
• Easy EE Testing: Test your playbooks and EEs against various network OS versions in a controlled CloudMyLab lab.
• Team Training: Provide standardized labs for your team to learn Navigator/EEs without individual setup headaches.
• POCs: Spin up environments quickly for Proof-of-Concept tests involving Navigator, EEs, and maybe AAP.

CloudMyLab removes the infrastructure roadblock, letting you focus on writing and testing your network automation using the consistent EE approach Navigator enables.

Conclusion

Ansible Navigator is the modern way to run Ansible from the command line, especially when using Execution Environments. It brings consistency, reliability, and better integration with AAP workflows compared to the old ansible-playbook command. Combined with CloudMyLab's easy-to-use lab infrastructure, you get an efficient setup for developing, testing, and validating your network automation.

💡 Why risk breaking production with untested automation? Use CloudMyLab's sandbox environments to test with confidence.

Check out our Ansible Network Automation offerings or start a free trial.

Learning Resources

Here are some helpful resources for learning more about Ansible:

• Ready to get started? Follow a practical guide on Ansible Setup Step-by-Step for quick environment setup and configuration.
• Dive deeper into modules: Check out a detailed guide: Ansible Modules Types Explained.
• Ansible Navigator documentation: https://ansible.readthedocs.io/projects/navigator/
• Source code on the Ansible Navigator Github repo: https://github.com/ansible/ansible-navigator
• Official Ansible Documentation:https://docs.ansible.com/
• Official Ansible labs by Red Hat:https://www.redhat.com/en/interactive-labs/ansible
• Ansible Forum:https://forum.ansible.com/

FAQ

What is the difference between Ansible playbook and Ansible Navigator?

ansible-playbook uses your local system's Python/libs. ansible-navigator uses containerized Execution Environments (EEs) for consistency and has an optional TUI.

Is Ansible content navigator the same with Ansible navigator?

The terms "Ansible Content Navigator" and "Ansible Navigator" refer to the same tool, officially named Ansible Navigator. The name "Ansible Content Navigator" is sometimes used in Red Hat documentation, particularly in the context of the Red Hat Ansible Automation Platform, but it is not a distinct product. Both terms describe the same command-line tool and text-based user interface designed for creating, reviewing, running, and troubleshooting Ansible content, such as playbooks, inventories, collections, and execution environments.

Do I need AAP to use Ansible Navigator?

No. You can use it standalone with Podman/Docker locally for development and testing with EEs. It just integrates well with AAP if you have it.

How do I manage Python dependencies with Navigator?

You don't manage them on your host for Navigator. Dependencies go inside the EE. Define them when building the EE using ansible-builder (via execution-environment.yml or requirements.txt). Navigator just uses the resulting EE image.