{"id":9955,"library":"molecule-vagrant","title":"Molecule Vagrant Driver","description":"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.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/molecule-vagrant","tags":["molecule","ansible","testing","vagrant","driver","virtualization"],"install":[{"cmd":"pip install molecule-vagrant","lang":"bash","label":"Install driver"}],"dependencies":[{"reason":"Core dependency for Molecule functionality.","package":"molecule","optional":false},{"reason":"Required external virtualization tool to provision instances.","package":"Vagrant (external tool)","optional":false},{"reason":"Required external virtualization provider for Vagrant to create VMs.","package":"Vagrant Provider (e.g., VirtualBox, Libvirt, VMware Workstation) (external tool)","optional":false}],"imports":[{"note":"molecule-vagrant is a plugin configured via molecule.yml, not typically imported directly in Python code by end-users.","wrong":"from molecule_vagrant import VagrantDriver","symbol":"driver.name","correct":"In molecule.yml:\ndriver:\n  name: vagrant"}],"quickstart":{"code":"# 1. Install Molecule and the Vagrant driver:\n# pip install molecule molecule-vagrant\n\n# 2. Ensure Vagrant and a provider (e.g., VirtualBox) are installed system-wide.\n\n# 3. Create a new Molecule project using the vagrant driver:\n# molecule init scenario --driver-name vagrant --role-name my-test-role\n\n# 4. Modify the generated molecule.yml to configure your Vagrant box:\n# This example uses 'generic/alpine316' for speed and minimal resources.\n\n# --- begin .molecule/my-test-role/molecule.yml ---\n# For a real project, replace 'my-test-role' with your actual role name.\n\n# lint: ignore\ndriver:\n  name: vagrant\n\nplatforms:\n  - name: instance\n    box: generic/alpine316\n    memory: 256\n    cpus: 1\n    provider_options:\n      memory: 256\n      cpus: 1\n\nprovisioner:\n  name: ansible\n  inventory:\n    group_vars:\n      all:\n        ansible_python_interpreter: /usr/bin/python3\n\nverifier:\n  name: ansible\n# --- end .molecule/my-test-role/molecule.yml ---\n\n# 5. Run your Molecule tests:\n# cd my-test-role\n# molecule test\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer before installing molecule-vagrant 2.0.0+.","message":"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.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"Ensure `ansible` is installed in your Python environment explicitly (e.g., `pip install ansible`) before running Molecule tests.","message":"The `ansible` extra dependency was removed in v1.0.0. Molecule-vagrant no longer automatically installs `ansible`.","severity":"breaking","affected_versions":"< 1.0.0"},{"fix":"Install Vagrant (https://www.vagrantup.com/downloads) and your chosen virtualization provider (e.g., VirtualBox https://www.virtualbox.org/wiki/Downloads) separately.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install Vagrant from its official website (https://www.vagrantup.com/downloads) and ensure it's accessible via your system's PATH.","cause":"The `vagrant` command-line tool is not installed or not found in your system's PATH.","error":"Failed to execute command Vagrant. Is it installed?"},{"fix":"Ensure `molecule-vagrant` is installed: `pip install molecule-vagrant`. Verify `driver.name: vagrant` in your `molecule.yml`.","cause":"The `molecule-vagrant` Python package is not installed in the active Python environment, or the driver name is misspelled in `molecule.yml`.","error":"ERROR! No such driver: vagrant"},{"fix":"Install `ansible` explicitly in your environment: `pip install ansible`.","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.","error":"Ansible not found in current path"},{"fix":"Switch to a Python environment running Python 3.9 or newer. Use `pyenv`, `conda`, or update your system Python.","cause":"Attempting to install or use `molecule-vagrant` v2.0.0+ with an unsupported Python version (e.g., 3.8 or older).","error":"Package 'molecule-vagrant' requires Python >=3.9, but you have Python X.Y."}]}