# ansible-navigator: a terminal interface for Ansible, with execution environments by default > ansible-navigator is an Apache-2.0 Python TUI that puts collections, inventories, documentation, images and playbook runs behind one curses interface, and it runs Ansible inside a container by default using podman or docker. It suits an Ansible user who wants a single place to work, and the container default is a real decision to check. **ansible/ansible-navigator** — A text-based user interface (TUI) for Ansible. - Repository: https://github.com/ansible/ansible-navigator - Website: https://ansible.readthedocs.io/projects/navigator/ - Stars: 557 · Forks: 134 - Language: Python - License: Apache-2.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/ansible-ansible-navigator ## One interface over the whole Ansible toolchain ansible-navigator is a text-based user interface for Ansible, and the packaging describes it as a text-based user interface for the Red Hat Ansible Automation Platform, with the project maintained by Ansible by Red Hat. What it does is give one place to work with the parts of Ansible that are usually separate commands. Running ansible-navigator with no arguments presents the welcome page, and from that page you can run playbooks, browse collections, explore inventories, read Ansible documentation, and more. A full list of key bindings can be viewed by typing:help. That welcome page is the design decision. Ansible's command line is a family of separate tools, each with its own flags, and the knowledge of which one to use and in what order is a real part of the learning curve. A single interface over them is closer to how the work actually goes, where you look up a module, check the inventory, then run the playbook. The same features are reachable as command-line subcommands, so nothing is locked inside the interface. The documented examples are: ```bash ansible-navigator collections ansible-navigator config ansible-navigator doc ansible.netcommon.cli_command ansible-navigator images ansible-navigator inventory -i inventory.yaml ansible-navigator run site.yaml -i inventory.yaml ``` and the mapping to the underlying Ansible commands is documented, with a full list of subcommands and their relation to Ansible commands in the subcommand documentation. So a subcommand is a shortcut into the interface rather than a different program, and the two ways of doing the same thing stay in sync. The licence is Apache 2.0, the project is at ansible.readthedocs.io under the navigator project, and the recent releases follow a calendar version scheme: v26.10.0 from 2026-10-12, v26.9.0 from 2026-09-23 and v26.8.0 from 2026-08-12, with the last push to the repository on 2026-10-13. ## The container default, and how to turn it off The single most consequential thing about ansible-navigator is not in the interface, and it is easy to miss in a quick read of the documentation. By default, ansible-navigator uses a container runtime, podman or docker, whichever it finds first, and runs Ansible within an execution environment, which is a pre-built container image that includes ansible-core along with a set of Ansible collections. That is a bigger change than it first appears. Without an execution environment, the collections a playbook can use are the ones installed in the Python environment or the system role, so two people running the same playbook on two machines can get different behaviour from different collection versions. With one, the environment is the image, and the image is pinned. The cost is a container runtime, a pull or build of the image, and the extra layer of indirection when something goes wrong and you need to know what is actually inside. The default can be disabled by starting ansible-navigator with --execution-environment false, and in that case Ansible and any collections needed must be installed manually on the system. For a team that has already invested in execution environments, this is exactly the right default, because the tool inherits the environment discipline rather than competing with it. For someone who installs ansible-core with pip and runs a playbook from a directory of role content, the default is friction, and the flag is the way out. The images subcommand exists to review the execution environment images available locally, which is how you find out what the tool is actually going to run. ## Interactive and stdout modes, and why the second one matters There are two modes in which ansible-navigator can be run, and the documentation defines them by what they do with curses. The interactive mode provides a curses-based user interface and lets you zoom in on data in real time, filter it, and navigate between the various Ansible components. The stdout mode does not use curses and simply returns the output to the terminal's standard output stream, as Ansible's commands would. The interactive mode is the default, and that default can be overwritten by passing --mode stdout, or -m stdout, or by setting mode in the configuration. The stdout mode is the part that makes the tool usable in a script, and it is a genuine design decision rather than a fallback. The examples given are: ```bash ansible-navigator config dump -m stdout ansible-navigator doc sudo -t become -m stdout ``` The first is a way of reading the effective configuration, which is the thing you need when a tool is behaving differently on two machines, and the second is a way of reading documentation for a module with a specific type of argument, which is a query rather than a browse. So the same subcommand tree serves two audiences. A person at a terminal gets the interface, with filtering and live views of large inventories and long playbook output. A script gets plain text on standard output, with no escape sequence handling required. That combination is what makes the tool more than a demo, because the components a team automates, the configuration dump and the documentation lookup, are exactly the ones you want to call from a shell script or a CI job. The docs/ directory in the repository and the mkdocs.yml at the root are what build the documentation site, and the configuration hierarchy is documented separately in the settings documentation, with the FAQ holding the list of common questions that the project actively invites additions to. ## Configuration precedence, and the packaging of the project There are several ways to configure ansible-navigator and users and projects are free to choose the most convenient method for them, and the full hierarchy of how the various configuration sources are applied is in the FAQ. The documented order of interest is short. Projects making use of ansible-navigator can include a project-wide configuration file with the project. If one is not found, ansible-navigator looks for a user-specific configuration file in the user's home directory. So a checked-in project file wins over a personal one. That is the right precedence for a team tool, and it has a consequence worth planning around: the file that changes how the tool behaves is the one in the repository, and it is therefore version-controlled, reviewable and shared. A setting that someone changes on their own machine and expects to apply to the team will not, because the project file takes precedence, and if there is no project file their personal setting applies only to them. The packaging is modern and thorough. The project uses setuptools with setuptools_scm, so the version is derived from the version control rather than written in the file, which is why the release numbers and the source stay in step. The classifiers list Development Status :: 5 - Production/Stable, Intended Audience :: Developers, the Apache Software License, OS Independent, and Python 3 only, with 3.10, 3.11, 3.12 and 3.13, on both CPython and PyPy, and requires-python is set to >=3.10. The command line entry point is declared in pyproject.toml as ansible_navigator.cli:main, and the rest of the repository matches a well-run Python project: a src/ directory, a tests/ directory, a tox.ini, a .pre-commit-config.yaml, a .flake8, a .yamllint, a .taplo.toml for TOML formatting, a cspell.config.yaml for spelling, a renovate.json for dependency updates, a sonar-project.properties for static analysis, a codecov.yml for coverage, a SECURITY.md, a CHANGELOG.md, a MANIFEST.in, a licenses/ directory and an ansible.cfg. ## Where ansible-navigator is the wrong tool The first limit is that it adds a layer to a workflow that Ansible already makes scriptable. If your team's practice is to write a small shell script that runs ansible-playbook with the right flags, or to use ansible directly in CI, then the TUI is a different front end to the same thing, and the value of a single interface over many commands is much lower when you only ever use one or two of them. The interface earns its keep for people who move between components constantly. The second is the container default in an environment that cannot run containers. A locked-down workstation, a hardened CI runner, or a host where the only container runtime is a rootless podman with a storage driver that does not fit, will all make the default path harder than the flag does. The documentation is clear that --execution-environment false exists, but the default is the default, and a tool that requires a flag to be usable in your environment is a tool you have to explain to everybody who joins. The third is the surface area of the tool itself. The package is a full application with a curses interface, an image and collection management layer, a documentation browser and a configuration system, and it runs a container runtime underneath. Every one of those is a thing that can be a different version from what you expect. The version number, the ansible-core inside the execution environment, the collections in the image, the Python version on the host, and the navigator version itself are five moving parts, and when a playbook behaves unexpectedly the first question is which of them changed. The fourth is the mode switch as a conceptual cost. Two modes with different output formats, one interactive and one for scripts, is convenient, and it also means the behaviour you depend on in a script is not the behaviour you saw on screen. A field that is filtered out of the interactive view is still there in stdout mode, so the two are not the same view of the same data. And the fifth is the audience. This is a developer and operator tool for people who already know Ansible, and the value of the interface assumes a mental model of collections, inventories, execution environments and playbook runs. Somebody who is new to Ansible will find that a TUI over a large toolchain is a harder way to learn than the underlying commands, where each one does one thing and the documentation for that one thing is a page. ## Conclusion ansible-navigator is worth installing if you already live in Ansible and want one interface for the whole toolchain, because the welcome page puts collections, inventories, documentation, images and playbook runs behind the same key bindings, because the stdout mode means the same subcommands work in a script as in the interface, and because the execution environment default means the collection versions a playbook sees are the ones in the image rather than whatever happens to be installed on the machine. It is the wrong tool if you want a single command per task, and it is the wrong tool if you cannot run containers. Before you adopt it, check three things: that you have Python 3.10 or newer, which is the stated requirement, with classifiers covering 3.10 through 3.13 on CPython and PyPy; that a container runtime is available, since by default it uses podman or docker, whichever it finds first, and turning that off with --execution-environment false means installing Ansible and the collections you need on the system yourself; and that you understand the configuration precedence, because a project-wide configuration file is used if one is found and otherwise a user-specific file in the home directory is used, and a file you did not know about will change how the tool behaves. ## FAQ ### How do I install ansible-navigator? Run pip3 install 'ansible-navigator[ansible-core]' and then ansible-navigator --help. The package requires Python 3.10 or newer, and the classifiers cover 3.10 through 3.13 on CPython and PyPy. Separate installation instructions for Linux, macOS and Windows with WSL2 are in the project's installation guide. ### How do I stop ansible-navigator from using a container? Start it with --execution-environment false. By default it uses a container runtime, podman or docker, whichever it finds first, and runs Ansible inside an execution environment, a pre-built container image containing ansible-core and a set of collections. With the flag disabled, Ansible and the collections you need must be installed on the system yourself. ### What is the difference between the interactive and stdout modes? The interactive mode is the default and uses a curses-based interface where you can zoom in on data, filter it and move between Ansible components. The stdout mode does not use curses and returns plain output to standard output, as Ansible's commands would, and you select it with --mode stdout, or -m stdout, or by setting mode in the configuration. Examples include ansible-navigator config dump -m stdout and ansible-navigator doc sudo -t become -m stdout. ## Sources - [ansible/ansible-navigator on GitHub](https://github.com/ansible/ansible-navigator) - [License: Apache-2.0](https://github.com/ansible/ansible-navigator/blob/main/LICENSE) - [Project website](https://ansible.readthedocs.io/projects/navigator/) - [README](https://github.com/ansible/ansible-navigator/blob/main/README.md) - [Releases](https://github.com/ansible/ansible-navigator/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ansible-ansible-navigator