Real Python: Python Virtual Environments: A Primer

In this tutorial, you’ll learn how to work with Python’s venv module to create and manage separate virtual environments for your Python projects. Each environment can use different versions of package dependencies and different versions of Python.

Once you’ve learned to work with virtual environments, you’ll be able to help other programmers reproduce your development setup and make sure that your projects never create dependency conflicts.

By the end of this tutorial, you’ll know how to:

• Create and activate a Python virtual environment
• Explain why you want to isolate external dependencies
• Visualize what Python does when you create a virtual environment
• Customize your virtual environments using optional arguments to venv
• Deactivate and remove virtual environments
• Choose additional tools for managing your Python versions and virtual environments

Working with virtual environments is a common and effective technique used in Python development. Gaining a better understanding of how they work, why you need them, and what you can do with them will help you master your Python programming workflow.

Throughout the tutorial, you can select code examples for either Windows, Ubuntu Linux, or macOS. Pick your platform at the top right of the relevant code blocks to get the commands that you need, and feel free to switch between them if you want to learn how to work with virtual environments on other operating systems.

Take the Quiz: Test your knowledge with our interactive “Python Virtual Environments: A Primer” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Python Virtual Environments: A Primer

In this quiz, you'll test your understanding of Python virtual environments. With this knowledge, you'll be able to avoid dependency conflicts and help other developers reproduce your development environment.

How Can You Work With a Python Virtual Environment?

If you just need to get a virtual environment up and running to continue working on your favorite project, then this section is for you.

This tutorial uses Python’s venv module to create virtual environments. This module is part of Python’s standard library, and it’s been the officially recommended way to create virtual environments since Python 3.5.

For basic usage, venv is an excellent choice because it already comes packaged with your Python installation. With that in mind, you’re ready to create your first virtual environment.

Create It

Any time you’re working on a Python project that uses external dependencies you’re installing with pip, it’s best to first create a virtual environment:

• Windows
• Linux
• macOS

PS> py-mvenvvenv\

PS> C:\Users\Name\AppData\Local\Programs\Python\Python312\python-mvenvvenv\

$ python3-mvenvvenv/

$ python3-mvenvvenv/

This command creates a new virtual environment named venv using Python’s built-in venv module. The first venv that you use in the command specifies the module, and the second venv/ sets the name for your virtual environment. You could name it differently, but calling it venv is a good practice for consistency.

Activate It

Great! Your project now has its own virtual environment. Generally, before you start to use it, you’ll activate the environment by executing a script that comes with the installation:

• Windows
• Linux + macOS

PS> venv\Scripts\activate(venv)PS>

$ sourcevenv/bin/activate
(venv)$

Before you run this command, make sure that you’re in the folder containing the virtual environment you just created. If you’ve named your virtual environment something other than venv, then you’ll have to use that name in the path instead of venv when you source the activation script.

Once you can see the name of your virtual environment in your command prompt—in this case (venv)—then you’ll know that your virtual environment is active. Now you’re all set and ready to install your external packages!