AnsibleByExample

ansible-navigator — TUI for Developing and Running Ansible Content

Beginneransibleansible-navigatorexecution environmentsdevelopment
2024-01-016By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Introduction

ansible-navigator is a text-based user interface (TUI) for running and developing Ansible content. It replaces ansible-playbook, ansible-doc, ansible-inventory, and ansible-config with a single tool that runs playbooks inside Execution Environments (container images) — the same way Automation Controller runs them. This means what works in your terminal works identically in production.

Install

# pip (recommended)
pip install ansible-navigator

# RHEL/CentOS
sudo dnf install ansible-navigator

# Ubuntu/Debian
pip install ansible-navigator

# Verify
ansible-navigator --version

Requirements

  • Python 3.10+
  • Container runtime: podman (preferred) or docker
  • An Execution Environment image (or uses ansible-navigator default EE)

Quick Start

# Run a playbook (interactive TUI)
ansible-navigator run site.yml

# Run a playbook (traditional stdout)
ansible-navigator run site.yml --mode stdout

# Explore collections in the default EE
ansible-navigator collections

# Browse module docs
ansible-navigator doc ansible.builtin.copy

# View your inventory
ansible-navigator inventory -i inventory.yml

ansible-navigator vs ansible-playbook

Featureansible-playbookansible-navigator
OutputStreaming textInteractive TUI or stdout
ExecutionLocal Python envInside Execution Environment
ReplayNoYes — artifact JSON
Collection docsSeparate ansible-docBuilt-in :doc
Inventory explorerSeparate ansible-inventoryBuilt-in :inventory
Config viewerSeparate ansible-configBuilt-in :config
EE supportNo (manual)Native
Image explorerNoBuilt-in :images

Modes

Interactive Mode (Default)

ansible-navigator run site.yml

Launches a TUI with navigable output:

  • Use number keys to drill into plays, tasks, hosts
  • Press :back or Esc to go up
  • Press :quit or q to exit
  • Type :help for all commands

Stdout Mode

ansible-navigator run site.yml --mode stdout

Produces traditional ansible-playbook-style output. Use in CI/CD pipelines.

Configuration

ansible-navigator.yml

# ansible-navigator.yml (project root)
---
ansible-navigator:
  execution-environment:
    container-engine: podman
    image: registry.redhat.io/ansible-automation-platform-25/ee-supported-rhel9:latest
    pull:
      policy: missing
    volume-mounts:
      - src: /home/user/.ssh
        dest: /home/runner/.ssh
        options: ro
    environment-variables:
      set:
        ANSIBLE_FORCE_COLOR: "true"

  mode: stdout

  playbook-artifact:
    enable: true
    save-as: artifacts/{playbook_name}-{time_stamp}.json

  logging:
    level: warning
    file: /tmp/ansible-navigator.log

  ansible:
    inventories:
      - inventory/production.yml
    config: ansible.cfg

Configuration Precedence

  1. Command-line flags
  2. ansible-navigator.yml in current directory
  3. ~/.ansible-navigator.yml
  4. Built-in defaults

Running Playbooks

Basic Run

ansible-navigator run site.yml \
  --inventory inventory/production.yml \
  --extra-vars "env=production" \
  --mode stdout

With a Custom EE

ansible-navigator run deploy.yml \
  --eei my-custom-ee:latest \
  --mode stdout

With Vault

ansible-navigator run site.yml \
  --vault-password-file .vault_pass \
  --mode stdout

Limit and Tags

ansible-navigator run site.yml \
  --limit webservers \
  --tags deploy,restart \
  --mode stdout

Exploring Execution Environments

List Available Images

ansible-navigator images

Output shows:

  • Image name and tag
  • ansible-core version inside
  • Python version
  • Installed collections
  • System packages

Inspect an EE

ansible-navigator images --eei ee-supported-rhel9:latest

Drill into:

  • 0 — General info
  • 1 — Ansible version and collections
  • 2 — Python packages
  • 3 — System packages
  • 4 — Everything

Browsing Collections and Docs

List Collections in EE

ansible-navigator collections

View Module Documentation

ansible-navigator doc ansible.builtin.copy
ansible-navigator doc community.general.proxmox_kvm
ansible-navigator doc ansible.builtin.uri --type module

Interactive Doc Browsing

ansible-navigator collections
# Navigate: select collection → select plugin type → select plugin

Inventory Explorer

ansible-navigator inventory -i inventory.yml
  • View groups, hosts, and variables
  • Drill into specific hosts to see all vars (including group_vars, host_vars)
  • Verify inventory structure before running playbooks

Replaying Artifacts

Every run produces a JSON artifact:

# Replay a previous run
ansible-navigator replay artifacts/site-2026-04-25T14:30:00.json

Navigate the replay exactly like a live run — drill into tasks, check host results, review variables. Share artifact files with teammates for debugging.

Using in CI/CD

# .github/workflows/ansible.yml
name: Run Ansible
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ansible-navigator
        run: pip install ansible-navigator

      - name: Run playbook
        run: |
          ansible-navigator run site.yml \
            --mode stdout \
            --eei ee-supported-rhel9:latest \
            --inventory inventory/staging.yml \
            --extra-vars "env=staging"

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ansible-artifact
          path: artifacts/

TUI Keyboard Shortcuts

KeyAction
Numbers (0-9)Select item
:back / EscGo back
:quit / qQuit
:helpShow help
:stdoutView raw stdout
:doc <module>View module docs
:inventorySwitch to inventory view
:configView ansible config
:logView log
/Filter/search
+ / -Page down/up

Troubleshooting

"Container engine not found"

# Install podman
sudo apt install podman
# or
sudo dnf install podman

# Verify
podman --version

"EE image pull failed"

# Login to registry first
podman login registry.redhat.io

# Or use a public EE
ansible-navigator run site.yml --eei quay.io/ansible/creator-ee:latest

"Playbook not found inside EE"

Volume mounts are needed — your project directory must be mounted:

# ansible-navigator.yml
ansible-navigator:
  execution-environment:
    volume-mounts:
      - src: /path/to/project
        dest: /runner/project

Falling Back to Local Execution

# Skip EE, run locally (like ansible-playbook)
ansible-navigator run site.yml --execution-environment false --mode stdout

Best Practices

  1. Use ansible-navigator.yml in every project — reproducible settings for the team
  2. Pin EE images — use tags like :2.16 not :latest
  3. Enable artifacts — free debugging replay for every run
  4. Use stdout mode in CI — interactive TUI doesn't work in pipelines
  5. Mount SSH keys read-only — options: ro in volume mounts
  6. Match EEs to production — use the same image locally and in Automation Controller
  7. Share artifacts for debugging — teammates can replay your exact run

Conclusion

ansible-navigator is the modern replacement for ansible-playbook. It runs playbooks inside Execution Environments (matching production), provides an interactive TUI for navigating results, saves replayable artifacts, and integrates collection docs, inventory exploration, and config viewing into one tool. Use --mode stdout for CI/CD and interactive mode for development. Pin your EE image in ansible-navigator.yml for reproducible runs across your team.

All Tutorials