Ansible Navigator

26.4.0 verified Mon Apr 27 auth: no python

A text-based user interface (TUI) for the Red Hat Ansible Automation Platform. Provides an interactive curses-based interface for running, reviewing, and debugging Ansible playbooks, inventories, and collections. Current version: 26.4.0, requires Python >=3.10. Release cadence follows Ansible Automation Platform releases.

pip install ansible-navigator

Common errors

error ModuleNotFoundError: No module named 'ansible_navigator' ↓

cause Package not installed or installed in wrong environment.

fix

Run 'pip install ansible-navigator' in the correct Python environment.

error ImportError: cannot import name 'AnsibleNavigator' from 'ansible_navigator' ↓

cause Incorrect import path; the class is nested under app submodule.

fix

Use 'from ansible_navigator.app import AnsibleNavigator'.

error curses.error: setupterm: could not find terminal ↓

cause Running in an environment without a proper terminal (e.g., headless).

fix

Set environment variable TERM=xterm or run with '--mode stdout'.

Warnings

breaking Version 2.x (ansible-navigator) changed CLI options significantly from 1.x (ansible-tui). Many flags were renamed or removed. ↓

fix Update to 2.x or later and refer to current documentation for CLI syntax.

deprecated The '--playbook-artifact' option has been deprecated in favor of '--artifact-format' and '--artifact-dir'. ↓

fix Use '--artifact-format' and '--artifact-dir' instead.

gotcha If running in a headless environment without a proper terminal (e.g., CI/CD), the TUI will fail. Use '--mode stdout' or set the environment variable ANSIBLE_NAVIGATOR_MODE=stdout. ↓

fix Set ANSIBLE_NAVIGATOR_MODE=stdout or pass --mode stdout to run without TUI.

gotcha The import path changed from 'ansible_navigator' to nested modules. Common top-level imports fail silently. ↓

fix Use correct imports like 'from ansible_navigator.app import AnsibleNavigator'.

gotcha Python 3.10+ is required. Installations on older Python versions will fail. ↓

fix Upgrade to Python 3.10 or later.

Install

pip install ansible-navigator[community]

Imports

AnsibleNavigator

wrong

from ansible_navigator import AnsibleNavigator

correct

from ansible_navigator.app import AnsibleNavigator

Incorrect top-level import; AnsibleNavigator class is under app module.

NavigatorConfiguration

from ansible_navigator.configuration_subsystem import NavigatorConfiguration

Quickstart

Launch the navigator TUI. The environment variable ANSIBLE_NAVIGATOR_CONFIG can point to a settings file.

from ansible_navigator.app import AnsibleNavigator
import os

os.environ['ANSIBLE_NAVIGATOR_CONFIG'] = ''  # optional, set to empty string for default
navigator = AnsibleNavigator()
navigator.run()