Python and Trellis
Trellis' main requirement is Python because Ansible is built with Python. This page documents the best way to install Python on your computer, how to manage Python package dependencies (like Ansible), common issues to avoid, and using trellis-cli to make your life easier.
When dealing with Trellis and Python, there's three key points:
- Make sure you have a stable version of Python 3 and pip installed
- Use trellis-cli since it handles dependencies for you
sudowhen installing packages with
Python 2 vs Python 3
Python 2 reached end-of-life in 2019 and hasn't been maintained since then. For that reason, newer version of Trellis (and trellis-cli) only support Python 3.
Unlike most languages that have a single version installed at a time, and only
offer an "unversioned" single binary path (such as just
node), Python can be
more confusing because most operating systems treat them separately with
python (which can be version 2 or 3 depending on your setup).
Regardless of the OS, it's still possible to symlink
convenience as well.
Newer versions of macOS like Monterey and Big Sur come with both versions 2 and
3. Annoyingly though, the unversioned
python is 2.7x while
python3 needs to
be explicitly used for Python 3.
While using the system Python on macOS should work fine, the main downside is that the versions are only updated when macOS itself has a new major version.
If you want to have more control over Python versions, we recommend using a tool like pyenv or asdf to install specific versions globally (or even per project if that's needed).
We do not recommend installing Python from Homebrew. This might be surprising since it goes against most guides and recommendations but we believe using Python from Homebrew will cause more problems long-term due to its newer "feature" of auto-upgrading packages as described in this article.
After Python is installed and working, you'll also need to ensure pip is installed. If
pip3 does not exist, it can be installed like this:
python3 -m ensurepip
Ubuntu 20.04 comes default with Python 3 available as
only. There's no "unversioned"
exists solely as an easy way to symlink
sudo apt-get install -y python3 python-is-python3 python3-pip
Roots recommends using WSL when using Windows. Since WSL uses Ubuntu, follow the Ubuntu section above.
Installing and managing dependencies
Once you have Python working, the next step is ensuring you can install Trellis'
dependencies. They are always declared in the
but mainly this involves installing Ansible.
pip is Python's package installer and what Trellis recommends using. But this is where trellis-cli comes in!
trellis-cli and Virtualenv
We strongly recommend using trellis-cli whenever possible since it will make your life managing dependencies and installing Ansible much easier.
trellis-cli uses Virtualenv to manage dependencies per project. It creates a "virtual environment" within each Trellis project so the dependencies are completely isolated. This allows different projects to have different versions of Ansible installed for example.
trellis-cli automatically creates a virtualenv and installs dependencies via pip at two points:
- when a new project is created with
trellis initis run for an existing project
Once the virtualenv exists, all other
trellis commands automatically use it.
This means running
trellis deploy production will activate the virtualenv
(within the CLI, for the lifetime of the command) and use the version of Ansible
within the virtual environment.
When using trellis-cli, you should almost never have to use
yourself. There's a more advanced Virtualenv integration offered as well. See
the README for more details.
Manually using pip
If you do need to run
pip manually to install Ansible, here's a few tips:
pip. It will only cause problems.
- Make sure you're using the version of pip that corresponds to your Python
version. If you're using Python 3, then you might need to use
- Avoid installing
ansibledirectly with pip. Instead run
pip install -r requirements.txtwithin a Trellis project to ensure you're getting a supported version of Ansible.
Help us continue to build and maintain our open source projects. We’re a small team of independent developers and every little bit helps.Sponsor Roots on GitHub