8 minute read

Ansible Navigator is a command-line tool and a text-based user interface (TUI) for creating, reviewing, running and troubleshooting Ansible content, including inventories, playbooks, collections, documentation and container images (execution environments).”

Currently Ansible Navigator for MacOS requires Docker Desktop and doesn’t support Podman due to other technical contraints on how podman handles mounting native folders on MacOS. At the time of writing this blog there is an open issue in the ansible-navigator repo for podman support issue 1259. Like me, if you’re unable to use Docker Desktop you may be looking for an alternative way to run Docker containers on MacOS, and with a general search you’ll find approaches such as using Lima or Vagrant. Lima, which stands for Linux on Mac, is a lightweight solution for running Linux VMs on MacOS, specifically with containerized applications, although it can also be used for non-container applications too.

Installing Lima

I used this blog post by Carlos Nunez as a guide for installing Lima on my laptop.

I’ll include a summary of the commands that I ran, but I’d recommend following Carlos’s blog for a detailed tutorial

╰─ brew install lima docker

╰─ limactl --version
  limactl version 0.19.0

╰─ mkdir ~/lima_machines

╰─ curl -sSLo ~/lima_machines/docker.yaml \

Edit the dockerfile as stated by the instructions in the file. Specifically:

  # NOTE: Replace %TEMPDIR% with your actual temporary directory as provided by
  # the $TMPDIR environment variable.
  - location: "%TEMPDIR%"
    writable: true

to which mine resolved to

╰─ echo $TMPDIR

We’re going to come back to the section in the file later as, we’ll need to update the mounts to include a new directory when we start using Ansible Navigator.

Next start the Docker VM:

╰─ limactl start ~/lima_machines/docker.yaml --tty=false

Perform a final export as mentioned in Carlos’s blog and then we’re good to go.

╰─ export DOCKER_HOST="unix://$HOME/.lima/docker.sock"

╰─ docker ps

Note, we’ll need to add this export to ~/.zprofile, which was not mentioned Carlos’s blog.

At this point we are now successfully running Docker on MacOS without Docker Desktop.

Installing Ansible Navigator

Next, we’re going to now install ansible-navigator and you can find the documented instructions here.

I’ll include a screenshot here just for posterity to have a record of the current instructions at the time of writing this blog.

Ensure that you export the appropriate ansible-navigator installation path as reported in the output of the installation.

╰─ echo 'export PATH=/Users/bpanyar/Library/Python/3.12/bin:$PATH' >> ~/.zprofile

╰─ source ~/.zprofile

After that you should be able to launch ansible-navigator:

╰─ ansible-navigator 

  Execution environment image and pull policy overview
  Execution environment image name:     ghcr.io/ansible/creator-ee:v0.20.0
  Execution environment image tag:      v0.20.0
  Execution environment pull arguments: None
  Execution environment pull policy:    tag
  Execution environment pull needed:    True
  Updating the execution environment
  Running the command: docker pull ghcr.io/ansible/creator-ee:v0.20.0
  v0.20.0: Pulling from ansible/creator-ee
  1e08c7e6aff8: Pull complete 
  ad97261d044b: Pull complete 
  7b05cec1a1b5: Pull complete 
  eaac7334e7ab: Pull complete 
  df17b198186c: Pull complete 
  6a4437d12ad5: Pull complete 
  90e5f6bd07c8: Pull complete 
  65aa82c7a1f1: Pull complete 
  897151f83099: Pull complete 
  19f93933b64e: Pull complete 
  8038a525cde8: Pull complete 
  11c3d85c8b64: Pull complete 
  d29defd3b078: Pull complete 
  Digest: sha256:b496e72a7b581fc8f437fab84d2e7f59c8a4e4ae8191d4c2478dd151c871cf1c
  Status: Downloaded newer image for ghcr.io/ansible/creator-ee:v0.20.0
 3│Some things you can try from here:
 4│- :collections                                    Explore available collections
 5│- :config                                         Explore the current ansible configuration
 6│- :doc <plugin>                                   Review documentation for a module or plugin
 7│- :help                                           Show the main help page
 8│- :images                                         Explore execution environment images
 9│- :inventory -i <inventory>                       Explore an inventory
10│- :log                                            Review the application log
11│- :lint <file or directory>                       Lint Ansible/YAML files (experimental)
12│- :open                                           Open current page in the editor
13│- :replay                                         Explore a previous run using a playbook artifact
14│- :run <playbook> -i <inventory>                  Run a playbook in interactive mode
15│- :settings                                       Review the current ansible-navigator settings
16│- :quit                                           Quit the application
18│happy automating,

Inspecting Execution Environment Image details

Going into the :images option you can see there is a default image called creator-ee which we’ll use to test running an initial playbook.

  Image                       Tag                 Execution environment                                   Created                           Size
0│creator-ee                  v0.20.0             True                                                    2 months ago                      843MB
1│qus                         latest              False                                                   7 months ago                      306MB

Inspecting the creator-ee image with option 0 lists a number of options of details that you can inspect about the image. By selecting option 1 you should see the following error:

  humph. Something went really wrong while introspecting the image.
  Details have been added to the log file
  [HINT] Please log an issue about this one, it shouldn't have happened

There will be a ansible-navigator.log file generated in your working directory which should show something along the lines of:

2023-10-27T21:08:07.304631+00:00 ERROR 'ansible_navigator.actions.images._parse' Unable to extract introspection from stdout
2023-10-27T21:08:07.305286+00:00 ERROR 'ansible_navigator.actions.images._parse' Image introspection failed (parsed), the return value was: /usr/bin/python3: can't open file '/Users/bpanyar/.cache/ansible-navigator/image_introspect.py': [Errno 2] No such file or directory

Which tells us that the reported ~/.cache directory is not accessible to the EE container. This is where we are going to go back to the docker.yaml file from earlier and update the mount section to incude this directory. We can either update the file we used previously at ~/lima_machines/docker.yaml or update ~/.lima/lima.yaml directly. If you choose to update the previous docker.yaml file, you need to copy it to ~/.lima/lima.yaml.

My mounts: section looks like this with the ~/.cache directory added to the bottom:

  - location: "~/src"
    writable: true
  - location: "~/tmp"
    writable: true
  # NOTE: Replace %TEMPDIR% with your actual temporary directory as provided by
  # the $TMPDIR environment variable.
  - location: "/var/folders/9p/5rymmxbs59d1svryg_7knth80000gn/T/"
    writable: true
  - location: "/tmp/lima"
    writable: true
  - location: "~/.config"
    writable: true
  - location: "~/.lima"
    writable: false
  - location: "~/.kube"
    writable: true
  - location: "~/.ssh"
    writable: false
  - location: "~/.gnupg"
    writable: false
  - location: "~/.cache"
    writable: false

Next, we need to restart the Docker VM with:

limactl stop docker && limactl start docker

After restarting Docker and re-launching ansible-navigator, we can now inspect all the image details of the creator-ee image.

Running a playbook with the sample EE.

For this I created a simple ping playbook which just pings localhost.


      ansible_host: localhost
      ansible_connection: local


- hosts: all
  gather_facts: false

    - name: run ping
      register: result

    - debug:
        var: result

To run the playbook with the default EE, I’ll change to the directory where this playbook is located and run the following command:

ansible-navigator run ping.yml -i inventory.yml

Note, by default ansible-navigator is configured to use the creator-ee. When creating your own execution environments you can use the --eei argument to specify the name of the execution environment image to use.

Immediately, you should see that the playbook runs without completing any tasks

  The playbook completed without tasks. Redirecting to ':stdout' for review.

And by pressing enter you should see something like:

0│ERROR! the playbook: /Users/bpanyar/Downloads/navigator-test/ping.yml could not be found

Again, this is due to the EE container not being able to access the working directory where our playbook is located, so we’ll need to go back and update the mounts: section in the ~/.lima/lima.yaml file and restart Docker again.

- location: "~/Downloads/navigator-test"
    writable: false

after doing that and re-running ansible-navigator run ping.yml -i inventory.yml you should see it execute successfully and be able to see that it completed 2 tasks and drill down into the play for more details.

  Play name        Ok   Changed       Unreachable          Failed      Skipped       Ignored       In progress          Task count                 Progress
0│all               2         0                 0               0            0             0                 0                   2                 Complete

Option 0

  Result         Host                  Number         Changed          Task               Task action                                   Duration
0│Ok             localhost                  0         False            run ping           ansible.builtin.ping                                0s
1│Ok             localhost                  1         False            debug              debug                                               0s

You can see the results of each task by entering its associated option number.

Play name: all:0
Task name: run ping
Ok: localhost                                                                                                                                               
 1│duration: 0.18527
 2│end: '2023-12-01T21:49:57.495027'
 3│event_loop: null
 4│host: localhost
 5│play: all
 6│play_pattern: all
 7│playbook: /Users/bpanyar/Downloads/navigator-test/ping.yml
 8│remote_addr: localhost
10│  _ansible_no_log: null
11│  ansible_facts:
12│    discovered_interpreter_python: /usr/bin/python3
13│  changed: false
14│  invocation:
15│    module_args:
16│      data: pong
17│  ping: pong
18│resolved_action: ansible.builtin.ping
19│start: '2023-12-01T21:49:57.309757'
20│task: run ping
21│task_action: ansible.builtin.ping
22│task_args: ''
23│task_path: /Users/bpanyar/Downloads/navigator-test/ping.yml:6

Also notice that there is a json file generated in the working directory for every run of playbook. This is a playbook artifact that contains details about the ansible-navigator settings along with the play output. This can be inspected manually, or replayed in ansible-navigator using the replay argument. This is especially helpful for sharing your playbook output with other or debugging someone elses play when you can’t recreate it in your own environment.

Note, there seems to be a bug with ansible-navigator and you may need to rename your playbook artifact to be able to replay it. The artifact is created with / in the file name and the replay option interprets them as child directories thus is not able to find the artifact.

╰─ ansible-navigator replay ping-artifact-2023-12-01T21/49/57.821234+00/00.json  
Warning: Issues were found while applying the settings.
   Hint: Command provided: 'replay ping-artifact-2023-12-01T21/49/57.821234+00/00.json'

  Error: The specified playbook artifact could not be found:
   Hint: Try again with 'replay <valid path to playbook artifact>'

   Note: Configuration failed, using default log file location. (/Users/bpanyar/Downloads/navigator-test/ansible-navigator.log) Log
         level set to debug
   Hint: Review the hints and log file to see what went wrong.


In summary, its definitely possible to use ansible-navigator without Docker Desktop, with a small amount of effort and some minor technicalities to be aware of. While its not an officially supported installation path, it seems to do the job for building and executing Ansible Execution Environments for development purposes. In this blog I only covered using the default Execution Environment included with Ansible Navigator, but in a future blog I’ll cover creating your own Execution Environments using ansible-builder.


  • Directories will need to be explicitely mounted for ansible-navigator and the EEs to accesss, so you may choose to mount a parent directory that holds all of your Ansible playbooks.

Many thanks to Carlos Nunez for the simple to follow instructions for installing Lima with Docker.