Python Development on macOS with pyenv-virtualenv

2 min readJul 12, 2017

UPDATED: April 29, 2021

This post is Part 2. Make sure you read Part 1: Python Development on macOS with pyenv.

At this point you should have pyenv installed. You can now quickly install and switch between any version of Python that you heart desires. But what if you want to use the same version of Python for two projects that use different versions of Django?!

We use pyenv-virtualenv.

From the docs:

pyenv-virtualenv is a pyenv plugin that provides features to manage virtualenvs and conda environments for Python on UNIX-like systems.

Installation Guide

Follow these steps to install pyenv-virtualenv on macOS. We’ll be installing pyenv-virtualenv via Homebrew so make sure you have it installed.

# Install Homebrew if it isn't already available
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"# Install pyenv-virtualenv
brew install pyenv-virtualenv# Add pyenv-virtualenv initializer to shell startup script
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile# Reload your profile
source ~/.bash_profile

Usage Guide

Yay! pyenv-virtualenv is installed and functioning. Now we can create virtual environments that use the same version of Python, but have their own set of pip installed packages.

Create Virtual Environment

pyenv virtualenv <python-version> <name>

This command will create a new virtual environment with whatever name you supply and use the specified Python version. Let’s create a new virtual environment using Python 3.9.4.

# Install Python 3.9.4
pyenv install 3.9.4# Create a new virtual environment
pyenv virtualenv 3.9.4 django-3.2

This creates a new virtual environment named django-3.2.

Activate Virtual Environment

Now that we’ve created our virtual environment, let’s activate it:

pyenv activate django-3.2

We are now in our virtual environment and we can install Django 3.2:

pip install django==3.2

This version of Django is only available in our virtual environment and it won’t conflict with anything else!

Just For Fun

Let’s go ahead and create another virtual environment for our project that uses Django 3.1 and see what happens.

pyenv virtualenv 3.9.4 django-3.1

Now let’s activate it:

pyenv activate django-3.1

And install our desired version of Django:

pip install django=3.1

Hot dog! We have the right version for this project and it doesn’t conflict with anything.

Activate Environment Automatically

As long as you followed the installation instructions and included the eval "$(pyenv virtualenv-init -)" line in your ~/.bash_profile, pyenv-virtualenv has the ability to automatically activate/deactivate your environment for you.

Anytime you change directories, pyenv looks for a .python-version file and uses the specified Python version or virtual environment!

cd into your project directory and run:

pyenv local django-3.2

Notice that you now have a .python-version file in your project. The next time you cd into the project, pyenv will read this file and activate the django-3.2 virtual environment for you!

Conclusion

Make sure to read the docs to better understand what both pyenv and pyenv-virtualenv can do. Now go enjoy developing without dependency conflicts!