Python venv Cheatsheet 🐍

Step by step breakdown of setting up a virtual environment for python project dependancy management

What is a Virtual Environment and Why Do we Need it?

If you install packages using pip ofr pip3 in your project, they will by default be installed globally. You can think of a virtual environment as npm and a package.json for your python project. Using a virtual environment will lock all of the versions of the packages you use for development. This is especially important in python development package maintainers will frequently introduce breaking changes, much more so than node package maintainers, and would believe that it is up to the dev (you) to version lock the packages you are using.

Steps to Set up a Virtual Environment with Git

Before installing or using any packages you must always activate a virtualenv, and you must deactivate it when you are finished. pip3 relies on the globally install packages unless you have a virtual environment running.

All python projects that use pip packages should be set up to use a virtual environment to ensure version control and package compatibility

Basic Virtual Environment Setup

In addition to this guide, refer to the ptyhon docs on venv and the pip docs on requirements files.

Create a project directory and cd into it
run pyhton3 -m venv venv to make a virtual environment in a directory named venv
- note the anatomy of this command is python3 -m venv < directory name >. Try experiment with different directory names once you are comfortable with this process!
start the virtual environment before installing needed packages:
- on mac/linux/WSL use source venv/bin/activate (any unix-based terminal)
- (on non-WSL windows use . venv/Scripts/activate)
make sure your virtual environment is active: (venv) can be seen in your terminal (if you are using a themed oh-my-zsh terminal that supports this display).
install the needed pip packages for the project (pip3 install < package name >)
once all your packages are installed, freeze the pip list in a requirements.text file
- use the command pip freeze > requirements.txt
- this needs to be done again if you add more pip packages to update the requirements.txt
- if you clone a python project from github, you can use pip install -r requirements.txt to install the needed packages
you can use the command deactivate to leave the virtual environment
every time you want to work on a python project with a virtual environment, you will need to activate it first
if you clone a repo from github with a virtual environment first install the needed packages with pip install -r requirements.txt and then run source venv/bin/activate (. venv/Scripts/activate on windows) to start the virtual environment.

Virtual Environments with git

the venv folder is like node_modules with node.js. It needs to be git ignored. By default when you create a new venv folder it includes a .gitignore inside of it. If for some reason the venv is not git ignored in your setup (older version of virtualenv), you can do these steps to ensure it is git ignored:

after you git init in your project, touch .gitignore and add venv and __pycache__ to it, so they don't get sent up to github.

Although it is not requed to add __pycache__ to your .gitignore for this to work, it is generally considered a good practice since they contain binares that just clutter up your repo on github.

Adding oh-my-zsh themes

If you do not have an oh-my-zsh theme that supports the (venv) display when in a virtual enviroment you can do the following: