Molecule Vagrant Driver

2.0.0 · active · verified Fri Apr 17

Molecule Vagrant is a plugin for the Molecule testing framework, enabling users to provision and test Ansible roles and playbooks on Vagrant-managed virtual machines. It integrates the robust local virtualization capabilities of Vagrant with Molecule's structured testing approach. The current version is 2.0.0, with releases typically aligning with major Molecule updates or significant breaking changes.

Common errors

```
Failed to execute command Vagrant. Is it installed?
```
cause The `vagrant` command-line tool is not installed or not found in your system's PATH.

fix Install Vagrant from its official website (https://www.vagrantup.com/downloads) and ensure it's accessible via your system's PATH.
```
ERROR! No such driver: vagrant
```
cause The `molecule-vagrant` Python package is not installed in the active Python environment, or the driver name is misspelled in `molecule.yml`.

fix Ensure `molecule-vagrant` is installed: `pip install molecule-vagrant`. Verify `driver.name: vagrant` in your `molecule.yml`.
```
Ansible not found in current path
```
cause Since `molecule-vagrant` v1.0.0, it no longer installs `ansible` as an extra dependency. If `ansible` is not globally installed or in your virtual environment, Molecule cannot find it.

fix Install `ansible` explicitly in your environment: `pip install ansible`.
```
Package 'molecule-vagrant' requires Python >=3.9, but you have Python X.Y.
```
cause Attempting to install or use `molecule-vagrant` v2.0.0+ with an unsupported Python version (e.g., 3.8 or older).

fix Switch to a Python environment running Python 3.9 or newer. Use `pyenv`, `conda`, or update your system Python.

Warnings

breaking Python 3.8 support was removed in v2.0.0. Python 3.6 and 3.7 support was removed in v1.0.0, and further reiterated in v2.0.0. The library now requires Python >= 3.9.
Fix: Upgrade your Python environment to 3.9 or newer before installing molecule-vagrant 2.0.0+.
breaking The `ansible` extra dependency was removed in v1.0.0. Molecule-vagrant no longer automatically installs `ansible`.
Fix: Ensure `ansible` is installed in your Python environment explicitly (e.g., `pip install ansible`) before running Molecule tests.
gotcha Molecule-vagrant requires the `vagrant` command-line tool and a Vagrant provider (e.g., VirtualBox, Libvirt, VMware Workstation) to be installed and configured on your host system.
Fix: Install Vagrant (https://www.vagrantup.com/downloads) and your chosen virtualization provider (e.g., VirtualBox https://www.virtualbox.org/wiki/Downloads) separately.
gotcha Specific versions of `molecule-vagrant` require compatible versions of `molecule`. For example, v1.0.0 requires `molecule >= 3.4.1`, and v0.5 required `molecule >= 3.2`.
Fix: Consult the `pyproject.toml` or `setup.cfg` of your `molecule-vagrant` version for the exact `molecule` dependency range and ensure you install a compatible `molecule` version.

Install

pip install molecule-vagrant Install driver

Imports

driver.name
wrong:
```
from molecule_vagrant import VagrantDriver
```
correct:
```
In molecule.yml:
driver:
  name: vagrant
```
molecule-vagrant is a plugin configured via molecule.yml, not typically imported directly in Python code by end-users.

Quickstart

This quickstart demonstrates how to initialize a Molecule scenario with the Vagrant driver, configure a basic Vagrant box in `molecule.yml`, and execute the Molecule test sequence. Remember that Vagrant and a provider must be installed separately on your system.

# 1. Install Molecule and the Vagrant driver:
# pip install molecule molecule-vagrant

# 2. Ensure Vagrant and a provider (e.g., VirtualBox) are installed system-wide.

# 3. Create a new Molecule project using the vagrant driver:
# molecule init scenario --driver-name vagrant --role-name my-test-role

# 4. Modify the generated molecule.yml to configure your Vagrant box:
# This example uses 'generic/alpine316' for speed and minimal resources.

# --- begin .molecule/my-test-role/molecule.yml ---
# For a real project, replace 'my-test-role' with your actual role name.

# lint: ignore
driver:
  name: vagrant

platforms:
  - name: instance
    box: generic/alpine316
    memory: 256
    cpus: 1
    provider_options:
      memory: 256
      cpus: 1

provisioner:
  name: ansible
  inventory:
    group_vars:
      all:
        ansible_python_interpreter: /usr/bin/python3

verifier:
  name: ansible
# --- end .molecule/my-test-role/molecule.yml ---

# 5. Run your Molecule tests:
# cd my-test-role
# molecule test

view raw JSON →