This document assumes the developer has a basic understanding of python packaging, and how to install and manage python on the system executing Molecule.
Depending on the driver chosen, you may need to install additional OS packages.
INSTALL.rst, which is created when initializing a new scenario.
Python >= 3.8 with Ansible >= 2.8
$ sudo dnf install -y gcc python3-pip python3-devel openssl-devel python3-libselinux
$ sudo apt update $ sudo apt install -y python3-pip libssl-dev
pip is the only supported installation method.
Ansible is not listed as a direct dependency of molecule package because we only call it as a command line tool. You may want to install it using your distribution package installer.
$ python3 -m pip install molecule ansible-core
ansible-base pip extras were removed in molecule
4.0.0. If you used them, please switch to explicit package mention to
avoid problem with newer versions of molecule.
Keep in mind that on selinux supporting systems, if you install into a virtual environment, you may face issue <https://github.com/ansible/ansible/issues/34340> even if selinux is not enabled or is configured to be permissive.
It is your responsibility to assure that soft dependencies of Ansible are available on your controller or host machines.
It is highly recommended that you install molecule in a virtual environment. This will provide a modern copy of setuptools which is mandatory in order for molecule to be installed successfully and function correctly. If you cannot use a virtual environment then you can attempt a package upgrade with the following:
$ python3 -m pip install --upgrade --user setuptools
Pip v19 series has an isolation bug <https://github.com/pypa/pip/issues/6264> of setuptools being exposed to the package build env. That is why it’s highly recommended to upgrade user setuptools even when using a proper virtualenv as shown above.
Depending on the driver chosen, you may need to install additional python
packages. See the driver’s documentation or
INSTALL.rst, which is created
when initializing a new scenario.
$ python3 -m pip install --user "molecule"
Molecule does not include ansible-lint (nor does the lint extra), but is easily installed separately:
$ python3 -m pip install --user "molecule ansible-lint"
Molecule uses the “delegated” driver by default. Other drivers can be installed separately from PyPI, such as the molecule-docker driver. If you would like to use docker as the molecule driver, the installation command would look like this:
$ python3 -m pip install --user "molecule[docker]"
Other drivers, such as
molecule-hetzner are also available.
Installing molecule package also installed its main script
PATH. Users should know that molecule can also be called as a
python module, using
python -m molecule .... This alternative method has
allows to explicitly control which python interpreter is used by molecule
allows molecule installation at user level without even needing to have the script in
We also have a continuous pre-release process which is provided for early adoption and feedback purposes only. It is available from test.pypi.org/project/molecule and can be installed like so:
python3 -m pip install \ --index-url https://test.pypi.org/simple \ --extra-index-url https://pypi.org/simple \ molecule==2.21.dev46
2.21.dev46 is the latest available pre-release version.
Please check the release history listing for the available releases.
Molecule is built into a Docker image by the Ansible Creator Execution Environment project.
Any questions or bugs related to use of Molecule from within a container should be addressed by the Ansible Creator Execution Environment project.
Due to the rapid pace of development on this tool, you might want to install and update a bleeding-edge version of Molecule from Git.
Follow the instructions below to do the initial install and subsequent updates.
The package distribution that you’ll get installed will be autogenerated and will contain a commit hash information making it easier to refer to certain unstable version should the need to send a bug report arise.
Please avoid using
-e development mode when
installing Molecule with Pip. This not very well supported and only
needed when doing development.
For contributing purposes, you can rely on the tox command line
interface. Please see our testing guide for further
$ sudo dnf install -y libffi-devel git
$ sudo apt install -y libffi-dev git
$ python3 -m pip install -U git+https://github.com/ansible-community/molecule