Text of realpython.com › python-virtual-environments-a-primer as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Python Virtual Environments: A Primer – Real Python

Python Virtual Environments: A Primer by Martin Breuss Updated Nov 30, 2024 Reading time estimate 1h 37m intermediate devops tools Table of Contents Remove ads Recommended Course Working With Python Virtual Environments (12m) Creating a Python virtual environment allows you to manage dependencies separately for different projects, preventing conflicts and maintaining cleaner setups. With Python’s venv module, you can create isolated environments that use different versions of libraries or Python itself.

This tutorial guides you through creating, activating, and managing these environments efficiently. By the end of this tutorial, you’ll understand that: Python virtual environments provide lightweight and isolated Python development environments. You can use Python’s venv module to manage dependencies independently for each project . You create and set up a venv in Python using the command python -m venv path/to/venv/ .

You refer to a virtual environment by the folder name that you used when creating the venv. You activate a venv on Windows with venv\Scripts\activate , and on macOS and Linux with source venv/bin/activate . You can enable a venv in VS Code by opening the Command Palette and choosing Python: Select Interpreter . Working with virtual environments is a common and effective practice 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.

Here’s the trap, in one demo: when two projects install their dependencies into a single shared environment, the second pip install silently overwrites the first—so client-old , which needs the older Django, breaks. Flip it to per-project virtual environments to watch both get exactly the version they need: Interactive diagram — enable JavaScript to view. Throughout the tutorial, you can select code examples for either Windows, 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. Get Your Cheat Sheet: Click here to download a free cheat sheet that summarizes the main venv commands you’ll learn about in this tutorial. 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. Note: There are other great third-party tools for creating virtual environments, such as conda and virtualenv , that you’ll learn more about later in this tutorial. Either of these tools can help you set up a virtual environment and also go beyond just that.

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. Remove ads 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 Language: Windows PowerShell PS> py -m venv venv \ This command allows the Python launcher for Windows to select an appropriate version of Python to execute.

It comes bundled with the official installation and is the most convenient way to execute Python on Windows . You can bypass the launcher and run the Python executable directly using the python command, but if you haven’t configured the PATH and PATHEXT variables, then you might need to provide the full path: Language: Windows PowerShell PS> C :\ Users \ Name \ AppData \ Local \ Programs \ Python \ Python312 \ python -m venv venv \ The system path shown above assumes that you installed Python 3.12 using the Windows installer provided by the Python downloads page .

The path to the Python executable on your system might be different. Working with PowerShell, you can find the path using the where.exe python command. Note: You don’t need to include the backslash ( \ ) at the end of the name of your virtual environment, but it’s a helpful reminder that you’re creating a folder. Language: Shell $ python3 -m venv venv/ Many Linux operating systems ship with a version of Python 3.

If python3 doesn’t work, then you’ll have to first install Python and you may need to use the specific name of the executable version that you installed, for example, python3.12 for Python 3.12.x. If that’s the case for you, remember to replace mentions of python3 in the code blocks with your specific version number. Note: You don’t need to include the slash ( / ) at the end of the name of your virtual environment, but it’s a helpful reminder that you’re creating a folder.

Language: Shell $ python3 -m venv venv/ Older versions of macOS come with a system installation of Python 2.7.x that you should never use to run your scripts. If you’re working on macOS < 12.3 and invoke the Python interpreter with python instead of python3 , then you might accidentally start up the outdated system Python interpreter. If running python3 doesn’t work, then you’ll have to first install a modern version of Python .

Note: You don’t need to include the slash ( / ) at the end of the name of your virtual environment, but it’s a helpful reminder that you’re creating a folder. 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 Language: Windows PowerShell PS> venv \ Scripts \ activate (venv) PS> If your attempt to run this command produces an error, then you’ll first have to loosen the execution policy . Language: Shell $ source venv/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. Note: You can also work with your virtual environment without activating it. To do this, you provide the full path to its Python interpreter when executing a command. However, you’ll likely want to activate the virtual environment after you create it to save yourself the effort of having to repeatedly type long pathnames.

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! Install Packages Into It After you’ve created and activated your virtual environment, you can install any external dependencies that you need for your project: Windows Linux + macOS Language: Windows PowerShell (venv) PS> python -m pip install < package-name > Language: Shell (venv) $ python -m pip inst

The rest of this page is on the live site.