How to Set Up a Virtual Environment

May 5, 2019

Motivation

Python applications often require different versions of libraries that can conflict when multiple projects are used on the same system. Virtual environments provide a way to avoid this problem by isolating each project into its own sandbox, keeping downloaded libraries separate from other projects.

Learning to use virtual environments can seem like a hassle and a bit cumbersome at first. In the long run, regular use of virtual environments will become second nature and can save you a lot of pain and frustration.

Quick Start

Windows

  1. Use where to verify python is in your %PATH%.
    This should list one or more full paths to python.exe.

    where python
    
  2. Change to your project directory.

    cd path\to\my-project
    
  3. Create a new virtual environment configuration using Python and the venv library.

    python -m venv venv
    
  4. Activate your virtual environment by running the activate script located under the new venv directory.

    venv\Scripts\activate
    
  5. Install additional packages with pip.
    Individual packages can be installed with pip install and the library name.

    pip install flask
    

    A list of packages contained in a requirements file can be installed using the -r flag.

    pip install -r requirements.txt
    
  6. Add a .gitignore file to the root of your project if one doesn’t exist.
    If the file does exist verify it contains a line with venv.

    See gitignore.io for easy generation of file contents (example with common tools)

    Note: the name of the file must be .gitignore

Mac / Linux

  1. Use which to verify python is in your $PATH.
    This should list the full path to a python3 binary.

    which python3
    
  2. Change to your project directory.

    cd path/to/my-project
    
  3. Create a new virtual environment configuration using Python and the venv library.

    python3 -m venv venv
    
  4. Activate your virtual environment by sourcing the activate script located under the new venv directory.

    source venv/bin/activate
    
  5. Install additional packages with pip.
    Individual packages can be installed with pip install and the library name.

    pip install flask
    

    A list of packages contained in a requirements file can be installed using the -r flag.

    pip install -r requirements.txt
    
  6. Add a .gitignore file to the root of your project if one doesn’t exist.
    If the file does exist verify it contains a line with venv.

    See gitignore.io for easy generation of file contents (example with common tools)

    curl -s 'https://www.gitignore.io/api/code,python,pycharm' > .gitignore
    

    Note: the name of the file must be .gitignore

General Tips

  • Activate the virtual environment (step 4. above) anytime you start a new command shell, otherwise the packages installed in that environment won’t be found.
  • The venv directory contains information specific to your computer and shouldn’t be checked into Git. This is the main reason for the explicit step to add a .gitignore file… and it’s a good practice 😎
  • GitHub offers an option to “Add .gitignore” when you create a new project.
    Select “Python” in the list for a shortcut on step 5.
  • Pypi.org is where pip finds the packages it downloads. The PyPi website offers search options for when you don’t know exactly which package to use.

Troubleshooting

If python isn’t found using the check in step 1. then it’s likely your PATH needs to be updated.

  • Windows users will need to find where python.exe resides on their file system and add that directory to their PATH within the control panel.
  • Mac / Linux users who installed python3 using homebrew should verify /usr/local/bin is in their PATH

    echo $PATH
    

    Update the PATH if absent (consider adding this to your .bashrc)

    export PATH="/usr/local/bin:$PATH"
    

    If that still doesn’t work, reach out in Slack.

Additional Resources