Hallo, I'm Julia.

Setting up virtual environments for Python repos


3 min read

I have to say that when I first came across the concept of setting up virtual environments for running Python, I found it extremely confusing. Despite installing the necessary Python versions I needed for a particular code, running pip install never seemed to work the way I felt it should intuitively, and I found the whole thing a bit hit and miss at the best of times.

After starting with a new team and Django code base this week, I finally got some help from another senior engineer about this and feel like I now understand where I've been going wrong. I thought I'd do a quick blog post on how to set up virtual environments for Python properly, mostly as a reference to myself as I'm sure I'm going to have to keep coming back to this in the future. ๐Ÿ™‚


First things first, pyenv. This basically allows you to install isolated versions of Python on your machine. You might need say Python v3.3 for one project, but Python v3.6 for another. pyenv allows you to have multiple Python version installs in your computer, allowing you to easily switch between them. Here are some useful commands:

  • python --version - checks current version of Python.
  • pyenv install 3.8.2 - installs Python version 3.8.2.
  • pyenv global 3.8.2 - sets the global version of Python to 3.8.2.

The various versions are saved in this directory (assuming you're on MacOS): ~/.pyenv/versions/

Some helpful resources that goes deeper into pyenv:

Creating virtual environments

I came across 2 ways of creating virtual environments in Python (which led to a lot of confusion). I'd really recommend reading this SO thread to understand the differences between venv and virtualenv.

Option 1: Using the shipped as standard venv feature in Python v3.3+. Note that it uses the current version of Python that it's installed for to create the virtual environment. It is not clear to me how you'd explicitly set the Python version - if anyone knows, please get in touch. To create a virtual environment for a different version of Python, see option 2.

  • python3 -m venv ~/[FOLDER]/[NAME OF ENV] - creates new virtual environment in the directory of your choice.
  • Navigate to the directory of your code repo and run source ~/[FOLDER]/[NAME OF ENV]/bin/activate to activate that virtual environment.
  • deactivate - deactivates the current virtual environment.

Option 2: Using virtualenv which is more explicit and also works with older versions of Python.

  • First download the right python version (see above with pyenv).
  • Install the pyenv-virtualenv package so that you can use pyenv and virtualenv together: brew install pyenv-virtualenv.
  • Then in ~ (or any directory), create a virtual environment with the specific Python version you want: pyenv virtualenv 3.7.10 ENVIRONMENT_NAME.
  • Check it worked and is listed using pyenv virtualenvs.
  • Navigate to the directory of your code repo and set the local environment explicitly: pyenv local ENVIRONMENT_NAME. To activate it, source ~/.pyenv/versions/covid_be/bin/activate. If you run pyenv virtualenvs, you should now see a star by the right Python version.
  • From here, you can proceed to run things like pip install -r requirements.txt from the directory of your repo.

ยฉ 2016-2023 Julia Tan ยท Powered by Next JS.