A Comprehensive Guide on Working with Python Virtual Environments
Published on May 23, 2024

Imagine you're a chef with one signature dish but want to experiment with different ingredients or cooking techniques. Instead of modifying your original recipe directly, you create identical copies of the dish. Each copy allows you to try new variations without altering the original recipe. This way, you can explore different flavors and methods while keeping the integrity of your main dish intact. Virtual environments (abbreviated as venv for this blog) are like having multiple of the same dish as a chef.

In this blog, you'll learn about Python virtual environments and how to work with them.

What Is a Python Virtual Environment?

A Python virtual environment is a self-contained Python environment containing a specific Python interpreter version and its associated dependencies.

These environments offer isolated copies of your Python environment, allowing you to install and test different packages without affecting your global Python environment. When you activate a virtual environment, the Python interpreter and packages installed in that environment take precedence over the global Python installation and other environments. That way, your project automatically uses the correct versions of dependencies.

Why Do You Need Virtual Environments?

Installing packages using pip within a virtual environment is the best practice to maintain a clean global environment and prevent accidental changes to system-wide packages. Additionally, there are some scenarios where using virtual environments can be beneficial:

  • When multiple projects use different package versions, virtual environments in Python development help manage dependencies separately, preventing conflicts between project requirements.

  • They are also helpful for creating isolated testing environments, allowing you to set up specific dependencies for testing new packages without impacting the main Python setup.

How to Use Tools to Create and Activate a Virtual Environment

There are several different tools you can use to create virtual environments, such as Conda, Pipenv, Poetry, and more. Two popular ones are virtualvenv and venv.

Using virtualenv

virtualenv is a third-party tool that is especially useful for managing environments with both new and older Python versions. The main difference with venv is that virtualenv is more flexible and customizable, so you can use it to create virtual environments with specific Python versions, custom package directories, and more. Here are some examples of how to use virtualenv.

  • Installation:

    • First, make sure you have Python installed on your system.

    • Install virtualenv using pip:

pip install virtualenv

  • Creating an environment:

    • Navigate to your project directory in the terminal.

    • Create a new virtual environment using virtualenv:

virtualenv myenv

Replace myenv with your desired environment name.

  • Activation:

    • On Windows:

myenv\Scripts\activate

  • On Unix or MacOS:

source myenv/bin/activate

Your command line prompt should now show the active virtual environment.

  • Install packages within the virtual environment

 pip install package_name

  • Deactivation:

    • Simply use the deactivate command:

deactivate

This will return you to the global Python environment.

By following these steps, you can effectively use virtualenv to manage your Python projects in isolated environments.

Using venv

venv is a module that comes built-in with Python 3 and is best used to create lightweight virtual environments. It creates isolated environments that have their own Python interpreter, package directories, and environment variables. Follow the following commands to use venv:

  • Creating a virtual environment

    • Navigate to your project directory in the terminal.

    • Create a new virtual environment using venv:

python -m venv myenv

Replace myenv with your desired environment name.

  • Activation

    • On Windows:

myenv\Scripts\activate.bat

  • On Unix or MacOS: bash source myenv/bin/activate Once activated, you can work within the active virtual environments as you would with a regular Python environment. You can install packages using pip, run Python scripts, and manage dependencies.

  • Install packages within the virtual environment

 pip install package_name

  • Deactivation:

  • Simply use the deactivate command:

deactivate
  • This will return you to the global Python environment.

How to Create Virtual Environments for Two Different Projects

Imagine you're building two projects using Vonage, each of which requires a different version of Flask. If you only have Flask installed on your operating system's global Python, you can't use two versions of the same package. To resolve this issue, let's create virtual environments for each project by following these steps:

1. Create the virtual environment for the first project:

  • On Unix/macOS and Windows:

  python3 -m venv project1_venv

2. Activate the virtual environment of the first project:

  • On Unix/macOS:

source project1_venv/bin/activate
  • On Windows:

project1_venv\Scripts\activate

3. (Optional) Set Environment Variables (e.g., for Flask and Vonage):

  • On Unix/macOS:

export FLASK_APP=app.py
export VONAGE_API_KEY=your_api_key
export VONAGE_API_SECRET=your_api_secret
  • On Windows:

set FLASK_APP=app.py
set VONAGE_API_KEY=your_api_key
set VONAGE_API_SECRET=your_api_secret

4. Install Flask (e.g., version 1.1.2) and Vonage for the first project:

On Unix/macOS and Windows:

pip install Flask==1.1. vonage

5. List installed packages

pip list

6. Create the virtual environment for the second project:

  • On Unix/macOS and Windows:

python -m venv project2_venv

7. Activate the virtual environment of the second project

  • On Unix/macOS:

source project2_venv/bin/activate
  • On Windows:

project2_venv\Scripts\activate

8. (Optional) Set Environment Variables (e.g., for Flask and Vonage):

  • On Unix/macOS:

export FLASK_APP=app.py
export VONAGE_API_KEY=your_api_key
export VONAGE_API_SECRET=your_api_secret
  • On Windows:

set FLASK_APP=app.py
set VONAGE_API_KEY=your_api_key
set VONAGE_API_SECRET=your_api_secret

9. Install a different version of Flask (e.g., version 2.0.1) and Vonage for the second project

  • On Unix/macOS and Windows:

pip install Flask==2.0.1 vonage

10. List installed packages

  • On Unix/macOS:

pip list

  • On Windows:

pip list

11. Verify Flask and Vonage versions:

  • On Unix/macOS and Windows:

flask --version
vonage --version

How to Avoid the "But It Works on My Machine" Problem

Let's say you built the most amazing application using Vonage, and now other people want to recreate it on their own machines. After setting up Vonage, Flask, and other dependencies in your virtual environment, freeze the dependencies into a requirements.txt file:

pip freeze > requirements.txt

Next, share your project and include the requirements.txt file in repo. The other people can then recreate your environment by cloning your repo and creating a virtual environment in their own project directory by running:

python -m venv venv
source venv/bin/activate  # On macOS/Linux
venv\Scripts\activate      # On Windows

Finally, they install dependencies from the requirements.txt file by running:

pip install -r requirements.txt

How to Deactivate the Virtual Environment

When you're done working in a virtual environment, you can deactivate it. Type deactivate in your terminal or command prompt and press Enter. This command will deactivate the currently active virtual environment, reverting your shell session to use the global Python environment.

deactivate

To Sum It Up

Python virtual environments are invaluable tools for Python developers, offering a way to create isolated environments for different projects with specific dependencies and configurations. They function like separate kitchens for chefs, allowing experimentation and customization without affecting the main recipe. By following best practices through using a Python module like venv or virtualenv, you can easily manage dependencies, prevent conflicts, and maintain clean project setups. Whether you're working on multiple projects with different requirements or testing new packages and configurations, virtual environments provide the flexibility and consistency needed for effective Python development workflows.

Additional Resources

Join the Party

If you liked this blog (or hated it), please let me know! Follow the Vonage Developer Experience team on X, formerly known at Twitter, or join the Vonage Community Slack channel. If you end up using virtual environments in your Python application, please share your experience and tag me - I'd love to hear about what you cheffed up!

Diana PhamDeveloper Advocate

Diana is a developer advocate at Vonage. She likes eating fresh oysters.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls-all at your fingertips.