Skip to content
Ansible role to install pyenv on Ubuntu or macOS development machines
Shell Dockerfile Makefile JavaScript
Branch: master
Clone or download


Ansible Quality Score Ansible Role GitHub release License

Branch Travis Builds Code Quality
master Build Status Build Status
develop Build Status Build Status

Ansible role to install pyenv and pyenv-virtualenv on Ubuntu or macOS development machines.

Optionally, pyenv-virtualenvwrapper can be installed and used for managing environments.

Don't use this role on production servers as it supports installing pyenv only under user home directory.

Install from Homebrew on macOS

The default method to install pyenv and plugins on macOS is to use Homebrew.

The role doesn't know how to migrate from existing Homebrew installs to Git-based installations, so it will try to detect any existing installation and keep using the previous method.

If you want to migrate, backup and delete your existing ~/.pyenv directory before running this role.

Installed Python versions

This role installs Python versions defined in pyenv_python_versions variable.

To set global version, set pyenv_global variable to the desired version(s).

pyenv_global: "{{ pyenv_python37_version }} system"

This is configured to use latest Python 2 and Python 3 versions and the system version as default.

Changes to shell config files

This role creates config file in ~/.pyenv/.pyenvrc that is loaded in .bashrc and .zshrc files.

Code completion is loaded by default.

If you're managing your shell scripts .dotfiles or are using a framework, you should set pyenv_init_shell to false and update these files yourself to keep them clean.

Reference .bashrc configuration:

if [ -e "$HOME/.pyenv/.pyenvrc" ]; then
  source $HOME/.pyenv/.pyenvrc
  if [ -e "$HOME/.pyenv/completions/pyenv.bash" ]; then
    source $HOME/.pyenv/completions/pyenv.bash
  elif [ -e "/usr/local/opt/pyenv/completions/pyenv.bash" ]; then
    source /usr/local/opt/pyenv/completions/pyenv.bash

Reference .zshrc configuration:

if [ -e "$HOME/.pyenv/.pyenvrc" ]; then
  source $HOME/.pyenv/.pyenvrc
  if [ -e "$HOME/.pyenv/completions/pyenv.zsh" ]; then
    source $HOME/.pyenv/completions/pyenv.zsh
  elif [ -e "/usr/local/opt/pyenv/completions/pyenv.zsh" ]; then
    source /usr/local/opt/pyenv/completions/pyenv.zsh

Role Variables

Path to ~/.pyenv is based on environment variables:

# Installation paths
pyenv_home: "{{ ansible_env.HOME }}"
pyenv_root: "{{ ansible_env.HOME }}/.pyenv"

Update .bashrc and .zshrc files in user home directory:

# Update .bashrc and .zshrc shell scripts
pyenv_init_shell: true

Versions to install.

# Versions to install
pyenv_version: "v1.2.13"
pyenv_virtualenv_version: "v1.1.5"
pyenv_virtualenvwrapper_version: "v20140609"

Latest Python 2 and Python 3 versions are installed:

# Latest Python versions
pyenv_python37_version: "3.7.6"
pyenv_python38_version: "3.8.1"

# Python versions to install
  - "{{ pyenv_python37_version }}"
  - "{{ pyenv_python38_version }}"

Set global version:

# Set global pyenv version
pyenv_global: "{{ pyenv_python37_version }} system"

Install virtualenvwrapper plugin:

# Optionally, install virtualenvwrapper plugin for pyenv
pyenv_virtualenvwrapper: false
pyenv_virtualenvwrapper_home: "{{ ansible_env.HOME }}/.virtualenvs"

Install using Homebrew on macOS:

# Install using package manager where available
pyenv_install_from_package_manager: false

Detect existing installation method and use that:

# Detect existing install
pyenv_detect_existing_install: true

Example Playbook

- hosts: localhost
  connection: local
  become: false
    - role: markosamuli.pyenv

Updating versions

Run the following scripts to get latest releases from GitHub and update them in role defaults.

Update pyenv release:

./update-release pyenv

Update pyenv-virtualenv release:

./update-release pyenv-virtualenv

Update default Python 3.7 version:

./update-python python37

Update default Python 3.8 version:

./update-python python38

Update all versions:

make update

Coding style

Install pre-commit hooks and validate coding style:

make lint

Run tests

Run tests in Ubuntu and Debian using Docker:

make test


Use of .pyenvrc file and parts used for installing python version taken from avanov.pyenv role.


Install pre-commit hooks:

make install-git-hooks



Author Information

You can’t perform that action at this time.