Molecule "molecule: command not found" in CI

By Kaveh Alemi·Latchkey

The shell could not find a molecule executable on PATH. Molecule is a pip package that is not preinstalled on GitHub-hosted runners, so the test step fails before any scenario runs.

What this error means

A step calling molecule test fails immediately with "molecule: command not found" and exit code 127, even though ansible --version may work.

/home/runner/work/_temp/script.sh: line 1: molecule: command not found
Error: Process completed with exit code 127.

Common causes

Molecule was never installed on the runner

GitHub-hosted runners ship Ansible in some images but not Molecule. Without a pip install molecule step, the executable does not exist.

Molecule installed into a different interpreter

A pip install ran against a Python that is not the one on PATH, or into a venv that the test step never activated, so molecule is not resolvable.

How to fix it

Install Molecule and its driver plugin

1. Add a step that installs Molecule before the test step.
2. Install the driver plugin you use (for example the docker plugin).
3. Invoke through python -m if PATH is unreliable.

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
- run: pip install "molecule" "molecule-plugins[docker]" ansible-core

Pin Molecule in a requirements file

Keep Molecule and its plugins in a test requirements file so CI installs a known version every run.

# test-requirements.txt
molecule==24.9.0
molecule-plugins[docker]==23.5.3
ansible-core>=2.16

How to prevent it

• Install Molecule from a pinned requirements file in every CI job.
• Use setup-python so pip and molecule land on the same interpreter.
• Cache the pip download directory to keep installs fast.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation