ansible-navigator.yml Explained: Settings, Execution Environments, and Verification

ansible-navigator.yml is the settings file for ansible-navigator—the terminal UI and runner wrapper around ansible-playbook. It configures how navigator presents and runs automation: UI mode (interactive vs stdout), execution environment images, logging, playbook artifacts, and navigator-specific paths to inventory and ansible.cfg. It does not replace ansible.cfg—SSH defaults, become, roles paths, and vault settings still live in ansible.cfg and are read by ansible, ansible-playbook, and ansible-galaxy.

This guide explains what belongs in the file, how it differs from ansible.cfg, where navigator looks for settings, and how to verify them on Rocky Linux 10. You need a project tree from project directory structure.

Before using this file, install ansible-navigator on the control node. Upstream currently recommends ansible-dev-tools for a full toolchain, or ansible-navigator directly when you only need navigator—see install Ansible. This article assumes the command is already available.

Tested on: Rocky Linux 10.2 (Red Quartz); kernel 6.12.0-211.16.1.el10_2.0.1.x86_64; ansible-core 2.16.16; ansible-navigator 26.6.0; Podman 5.8.2.

What is ansible-navigator.yml?

ansible-navigator.yml is the settings file for ansible-navigator—Red Hat’s terminal UI and runner front end around ansible-playbook. Where ansible.cfg tells the Ansible engine which inventory and SSH defaults to use, ansible-navigator.yml tells navigator how to run that engine: interactive or stdout UI, execution environment (container) image, artifact storage, and logging. Day-to-day playbook flags (--check, --limit, tags) live in how to run Ansible playbooks.

Navigator subcommands that respect the file include:

The file is YAML or JSON with a single top-level key:

---
ansible-navigator:
  mode: stdout
  execution-environment:
    image: ghcr.io/ansible/community-ansible-dev-tools:latest

Navigator reads one settings file per invocation. It does not merge ./ansible-navigator.yml with ~/.ansible-navigator.yml—the first match in the search order wins entirely.

Why Use ansible-navigator.yml?

Without a settings file you repeat flags on every run:

ansible-navigator run playbooks/site.yml --mode stdout -i inventory/hosts --eei ghcr.io/ansible/community-ansible-dev-tools:latest

With ansible-navigator.yml at the project root:

ansible-navigator run playbooks/site.yml --mode stdout

The file gives you a single place to document how your team runs navigator: which EE image matches production, whether CI uses stdout mode, where artifacts land, and which inventory path every subcommand should use. New contributors cd into the repo and get the same behavior without copying a long shell alias.

Settings can also come from environment variables (ANSIBLE_NAVIGATOR_*) or CLI flags—they override the file for that run. The file is the baseline; flags win when you need a one-off change.

ansible.cfg vs ansible-navigator.yml

Keep both at the project root. ansible.cfg drives Ansible engine behavior; ansible-navigator.yml drives how navigator wraps that engine (container image, TUI, runner artifacts).

Example split for ~/ansible-project:

How ansible-navigator Finds Its Settings File

Like ansible.cfg, navigator resolves settings from the directory where you run the command. cd ~/ansible-project before ansible-navigator run so it picks up ./ansible-navigator.yml beside your playbooks.

ansible-navigator.yml Search Order

Navigator loads the first match and stops:

Only one file is used—project and home settings are not merged.

YAML and JSON File Names

Navigator accepts YAML or JSON. The filename pattern differs between project and home directories—mixing them up is a common copy-paste mistake.

The project directory uses no leading dot; the home file uses a dot prefix. More than one settings file in the same directory causes an error.

Project-Level vs Home-Level Settings File

Use ./ansible-navigator.yml in your Ansible repo so settings travel with Git and sit beside ansible.cfg and inventory.

Use ~/.ansible-navigator.yml for personal defaults that apply to every project on your laptop:

---
ansible-navigator:
  editor:
    command: vim
  mode: interactive

Keep project-specific values—EE image, inventory path, artifact directory—in the repo file. Keep editor choice and UI mode preference at home level if you like.

Settings precedence

For any navigator option, effective value is chosen in this order (highest wins):

1. Command-line flag (--mode stdout, --ee false)
2. Environment variable (ANSIBLE_NAVIGATOR_MODE, ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_IMAGE, …)
3. Settings file (./ansible-navigator.yml or ~/.ansible-navigator.yml)
4. Built-in default

Check where a value came from with ansible-navigator settings --mode stdout and read the source: field for each setting.

Basic ansible-navigator.yml File Structure

A practical starter file for ~/ansible-project:

---
ansible-navigator:
  ansible:
    config:
      path: ./ansible.cfg
    inventory:
      entries:
        - inventory/hosts
  execution-environment:
    enabled: true
    image: ghcr.io/ansible/community-ansible-dev-tools:latest
    container-engine: podman
    pull:
      policy: missing
  logging:
    level: warning
    file: ansible-navigator.log
  playbook-artifact:
    enable: true

Nested keys group related behavior:

You do not need every block on day one. Start with ansible.inventory.entries, execution-environment, and logging; add artifacts and volume mounts when you debug runs or customize images.

Configure stdout and interactive Mode

Navigator supports two UI modes. Pick per command or set a default in the file.

Use stdout mode for terminal-friendly output

mode: stdout prints playbook output line by line—ideal when SSH does not allocate a TTY (automated editors, CI, remote Cursor terminal):

ansible-navigator:
  mode: stdout

Or per command without editing the file:

ansible-navigator run playbooks/ping-lab.yml --mode stdout

If you run ansible-navigator settings without --mode stdout over SSH, curses often fails with cbreak() returned ERR. Always add --mode stdout for headless verification commands.

Use interactive mode for TUI-based navigation

Interactive mode is the default when mode is unset. On the rocky1 console:

ansible-navigator run playbooks/ping-lab.yml

The TUI lets you review each task, jump to module docs, and inspect variables—useful when you are learning collections for EX294. Set the default explicitly when the whole team lives in the TUI:

ansible-navigator:
  mode: interactive

Configure Execution Environment Settings

Execution environments (EE) run playbooks inside an OCI image (Podman or Docker on Rocky Linux) that bundles a known Ansible version, Python, and collections. Navigator launches the container, mounts your project, and runs ansible-playbook inside so every teammate uses the same toolchain.

First run with pull.policy: missing may download ~1.3 GB for community-ansible-dev-tools—plan disk and network once; later runs reuse the local image.

Enable or disable execution environments

Turn execution environments on when navigator should run playbooks inside a container image. Keep execution environments enabled when your course, team, or lab workflow expects ansible-navigator to run through a container image:

execution-environment:
  enabled: true

Turn them off when you want navigator to call the same ansible-playbook binary installed on rocky1—no image pull, easier debugging:

execution-environment:
  enabled: false

Run once without EE:

ansible-navigator run playbooks/ping-lab.yml --mode stdout --ee false

Configure execution environment image

The image name is the OCI reference Podman pulls and runs. The community dev-tools image ships a curated Ansible + collections stack:

execution-environment:
  image: ghcr.io/ansible/community-ansible-dev-tools:latest

Pin a digest or version tag in production (:latest moves when upstream rebuilds). Override once from the CLI with --eei when comparing two images.

Configure image pull policy

Control when Podman contacts the registry. Navigator’s default pull policy is tag; for a lab, missing is often easier because the image is pulled once and reused.

Labs on rocky1 usually set missing explicitly so the first run pulls once and later runs stay offline-friendly:

execution-environment:
  pull:
    policy: missing

Configure container engine

Navigator talks to Podman or Docker to start the EE container. On Rocky Linux 10, set Podman explicitly after dnf install podman:

execution-environment:
  container-engine: podman

Leave container-engine unset or set auto to try Podman first, then Docker. The engine must be installed for the user running navigator—not root-only Docker unless your lab user is in the docker group.

Configure volume mounts

By default navigator mounts your playbook directory into the EE. Custom mounts expose extra paths—roles checked out elsewhere, shared certificates, or the whole project root:

execution-environment:
  volume-mounts:
    - src: "."
      dest: "/runner/project"
      options: "Z"
    - src: "/etc/ansible/certs"
      dest: "/etc/ansible/certs"
      options: "ro,Z"

options: "Z" on RHEL/Rocky relabels content for container SELinux. Use ro for read-only mounts. Paths must exist on the control node before the run starts.

Pass environment variables to the execution environment

Corporate proxies and locale settings often need to reach the container:

execution-environment:
  environment-variables:
    pass:
      - HTTP_PROXY
      - HTTPS_PROXY
      - NO_PROXY
    set:
      ANSIBLE_NOCOLOR: "1"
      LANG: C.UTF-8

pass copies variables from your shell if they are set. set defines constants inside the EE regardless of the host environment—useful for forcing ANSIBLE_NOCOLOR in recorded CI logs.

Configure Ansible Settings Used by Navigator

Navigator wraps Ansible CLI tools. Point it at project files instead of repeating flags.

Configure ansible.cfg path

Point navigator at the same INI file you use for ansible-playbook in this repo:

ansible:
  config:
    path: ./ansible.cfg

Relative paths resolve from the project root. This should match the file created in the ansible.cfg lesson and the project layout tree.

Configure inventory entries

Prefer structured inventory entries over stuffing -i into cmdline:

ansible:
  inventory:
    entries:
      - inventory/hosts

List hosts in stdout mode:

cd ~/ansible-project
ansible-navigator inventory --mode stdout --list

Sample output (trimmed):

{
    "_meta": {
        "hostvars": {
            "rocky2": {
                "ansible_host": "192.168.56.109",
                "ansible_user": "ansible"
            }
        }
    },
    "lab": {
        "hosts": [
            "rocky2"
        ]
    }
}

Configure playbook path

Set a default playbook when your workflow always runs the same entry point—site deploy or a demo ping play:

ansible:
  playbook:
    path: playbooks/site.yml

Most teams still pass the playbook on the command line so CI can target different files without editing navigator settings.

Pass extra Ansible command-line options

Append global flags to every underlying Ansible call navigator makes. Use only for options that apply broadly—parallelism is a common example:

ansible:
  cmdline: --forks 10

Avoid putting -i or inventory paths here; invalid cmdline values break navigator subcommands. Prefer ansible.inventory.entries and ansible.config.path instead.

Configure Playbook Artifacts

When playbook-artifact.enable is true, navigator saves a JSON artifact for each run—task results, timing, and stdout snippets ansible-runner captured. Artifacts power ansible-navigator replay and help compare a failed run without re-executing modules on production.

Enable or disable playbook artifacts

Artifacts are JSON snapshots of each run. Enable them when you want replay or post-mortem review:

playbook-artifact:
  enable: true

Set enable: false when disk space is tight or you only care about live terminal output.

Change artifact save location

By default artifacts may land under a cache directory in your home. Redirect them into the project for easier cleanup:

ansible-runner:
  artifact-dir: ./artifacts
  rotate-artifacts-count: 5

If artifact-dir is unset, navigator uses a per-user cache directory under your home. Explicit ./artifacts keeps run history beside the repo—add artifacts/ to .gitignore because artifacts can contain sensitive task output.

rotate-artifacts-count: 5 keeps the five newest artifact directories and deletes older ones.

Replay a previous artifact

After a run, list artifact directories:

ls artifacts/

Replay one in stdout mode:

ansible-navigator replay artifacts/1-artifact-job.json --mode stdout

Or pin a default replay target in the file while debugging the same failure repeatedly:

playbook-artifact:
  replay: artifacts/1-artifact-job.json

Replay reuses recorded results—it does not SSH to managed nodes again unless the replay workflow triggers a new run.

Configure Logging

Navigator writes its own diagnostic log—separate from playbook stdout and from Ansible’s default logging. Enable it when EE pulls, container mounts, or runner queues fail and the terminal only shows a short error.

logging:
  level: warning
  file: ansible-navigator.log
  append: true

With append: true, repeated runs accumulate in one file. Use append: false to truncate each session.

After a playbook run, inspect the tail:

tail -5 ansible-navigator.log

Sample line:

Sample output:

2026-07-07T05:33:47.511343+00:00 WARNING 'ansible_navigator.main' `config was normalized to ...

Add ansible-navigator.log to .gitignore—logs may reference host paths or proxy settings you do not want in Git.

Configure Editor Settings

Interactive mode can open a playbook or inventory file for editing—navigator uses the program you set here:

editor:
  command: vim
  console: false

Editor settings matter only for interactive workflows. They are ignored for ansible-navigator run --mode stdout in CI.

Verify ansible-navigator.yml Settings

Work from ~/ansible-project so navigator loads ./ansible-navigator.yml.

Show active Navigator settings

Dump every navigator parameter, its current value, and whether the file, environment, or CLI set it:

ansible-navigator settings --mode stdout

The output is long YAML. Filter for the active file and a specific setting:

ansible-navigator settings --mode stdout 2>/dev/null | grep -A3 "current_settings_file\|name: Execution environment image\|name: Pull policy"

Sample output:

current_settings_file: /home/ansible/ansible-project/ansible-navigator.yml
  ...
  name: Execution environment image
  source: Settings file
  ...
  name: Pull policy
  source: Settings file

current_settings_file confirms which file navigator loaded. source: Settings file means your YAML overrode the default; source: Command line means a flag won for that run.

Run ansible-navigator in stdout mode

End-to-end check: navigator loads your YAML, reaches inventory, and completes a playbook:

ansible-navigator run playbooks/ping-lab.yml --mode stdout

Sample output:

PLAY [Ping lab hosts] **********************************************************

TASK [Ping] ********************************************************************
ok: [rocky2]

PLAY RECAP *********************************************************************
rocky2                     : ok=1    changed=0    unreachable=0    failed=0

A successful recap means navigator, inventory, and EE (or local Ansible) agree with your settings.

Inspect Ansible configuration

For scripts and this lab, prefer the engine CLI—it reads the same ansible.cfg navigator uses:

ansible-config dump --only-changed

Sample output:

CONFIG_FILE() = /home/ansible/ansible-project/ansible.cfg
DEFAULT_HOST_LIST(/home/ansible/ansible-project/ansible.cfg) = ['/home/ansible/ansible-project/inventory/hosts']
DEFAULT_REMOTE_USER(/home/ansible/ansible-project/ansible.cfg) = ansible

View the raw INI file:

ansible-config view

ansible-navigator config opens an interactive browser for the same data on a real terminal. If ansible-navigator config --mode stdout behaves differently on your installed version, use ansible-config dump --only-changed directly from the project directory—it is the most reliable way to verify the active ansible.cfg.

Inspect inventory

Confirm ansible.inventory.entries resolves to the same hosts as ansible-inventory on the control node:

ansible-navigator inventory --mode stdout --list

You should see rocky2 under lab with ansible_host and ansible_user in _meta.hostvars when the project inventory matches the group_vars and host_vars patterns from this course.

List available execution environment images

Show images Podman already has locally—verify the name in your YAML before a long playbook run:

ansible-navigator images --mode stdout

Sample output:

---
- execution_environment: true
  full_name: ghcr.io/ansible/community-ansible-dev-tools:latest
  image_id: ce7e764dcf45

Podman may print cgroup warnings on minimal SSH sessions—they are usually harmless if the image list still appears.

Run a Playbook Using ansible-navigator.yml

Navigator loads settings before any subcommand. Work from the project root so it finds ./ansible-navigator.yml:

cd ~/ansible-project

Confirm the settings file is active:

ansible-navigator --version

Sample output:

ansible-navigator 26.6.0

Run the lab ping playbook in stdout mode:

ansible-navigator run playbooks/ping-lab.yml --mode stdout

Navigator reads ansible-navigator.yml, uses inventory from ansible.inventory.entries (or ansible.cfg inside the EE), and pulls the EE image according to your pull.policy when the image is not already local.

On the rocky1 graphical or virtual console, omit --mode stdout for the interactive TUI:

ansible-navigator run playbooks/ping-lab.yml

The same settings file backs both modes—only the UI layer changes.

Common ansible-navigator.yml Mistakes and Fixes

Most navigator issues trace back to working directory, mixed config files, or headless SSH. Use this table when settings look ignored or subcommands fail:

Recommended ansible-navigator.yml for a Learning Lab

The file below matches ~/ansible-project on rocky1: project ansible.cfg and inventory, community dev-tools EE, local log file, artifacts on, interactive default on the console.

Create or replace the file:

cd ~/ansible-project

---
ansible-navigator:
  ansible:
    config:
      path: ./ansible.cfg
    inventory:
      entries:
        - inventory/hosts
  execution-environment:
    enabled: true
    image: ghcr.io/ansible/community-ansible-dev-tools:latest
    container-engine: podman
    pull:
      policy: missing
  logging:
    level: warning
    file: ansible-navigator.log
  playbook-artifact:
    enable: true
  mode: interactive

Save as ansible-navigator.yml in the project root. Pair with ansible.cfg and inventory from project directory structure. For quick checks without containers, run with --ee false or set execution-environment.enabled: false.

When Should You Disable Execution Environments?

Disable EE when local ansible-core on rocky1 is enough:

execution-environment:
  enabled: false

One-off disable without editing the file:

ansible-navigator run playbooks/ping-lab.yml --mode stdout --ee false

That run uses /usr/bin/ansible-playbook from AppStream with your project ansible.cfg—no image pull.

What Not to Put in ansible-navigator.yml

Navigator settings are not a shortcut for the whole project. Putting playbooks, secrets, or engine defaults in this file confuses newcomers and breaks precedence. Keep responsibilities split:

ansible-navigator.yml configures navigator itself—not your automation content.

What comes next

1. Ansible inventory files — groups and variables
2. Ansible playbook examples — multi-task YAML
3. Install ansible-navigator and Podman — control node setup

References

• ansible-navigator settings (official)
• ansible-navigator installation
• Ansible configuration settings

Summary

ansible-navigator.yml configures ansible-navigator—UI mode, execution environment image, logging, artifacts, and paths to ansible.cfg and inventory. Place it at the project root as ansible-navigator.yml, keep ansible.cfg for engine defaults, and verify with ansible-navigator settings --mode stdout and a test run. Disable execution environments when local ansible-core is enough; enable them when you need a consistent container image.