Python Virtual Environments with venv: What They Are and How to Use Them

What a Python virtual environment is, why you should use one in every project, and how to create, activate and manage it with venv on Windows and Linux.

Python Virtual Environments with venv: What They Are and How to Use Them

As soon as you start using Python seriously, you run into a problem: every project needs its own libraries, sometimes in different versions. One script wants a certain version of a library, another project wants a newer one, and installing everything in the same place sooner or later leads to conflicts that are hard to understand.

The solution is called a virtual environment. In this guide we look at what it is, why it is worth always using one and how to manage it with venv, the tool included with Python, on both Windows and Linux.

What is a virtual environment

A virtual environment is a folder that contains an isolated copy of Python with its own libraries. When the environment is active, everything you install ends up in there, and not in the computer's general Python.

You can think of it as a toolbox dedicated to a single job: each project has its own, with the tools it needs, and the boxes never get mixed up.

There are three concrete advantages:

  • No conflicts: two projects can use different versions of the same library.
  • The system stays clean: on Linux in particular, you do not risk damaging the Python used by the operating system.
  • The project is reproducible: you can recreate the same environment on another computer or on a server with a single command.

Before you start

You need Python already installed. On Ubuntu and Debian, also make sure you have the venv module, which is not always present:

sudo apt install python3-venv

On Windows, if you installed Python with the Python Install Manager, venv is already included.

Creating a virtual environment

Open the terminal in your project folder and type:

# Windows
python -m venv .venv

# Linux and macOS
python3 -m venv .venv

The command creates a folder called .venv containing everything you need. The name is a very common convention: the leading dot makes it “hidden” on Linux, and most editors recognise it automatically. You can call it whatever you like, but .venv is the most convenient choice.

On Windows, if you have several Python versions installed, you can choose which one to create the environment with:

py -V:3.14 -m venv .venv

The environment will always use the version it was created with.

Activating the environment

Creating the environment is not enough: you have to activate it every time you open a new terminal to work on the project. The command depends on the system:

# Windows, Command Prompt
.venv\Scripts\activate

# Windows, PowerShell
.venv\Scripts\Activate.ps1

# Linux and macOS
source .venv/bin/activate

When the environment is active, its name appears in brackets at the start of the terminal line, for example (.venv). That is the sign that you are working inside the environment.

If PowerShell blocks the activation script with an execution policy error, allow local scripts to run for your user with this command, which you only need to run once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Installing libraries

With the environment active, libraries are installed with pip, Python's package manager:

python -m pip install requests

Why python -m pip and not simply pip? Because that way you can be sure pip installs the library into the very Python you are using. With the pip command on its own, if the environment is not active or several versions are installed, the library could end up in the wrong place. It is a small habit that avoids many problems.

To see the libraries installed in the environment:

python -m pip list

Saving and recreating dependencies with requirements.txt

The libraries a project uses are called dependencies. To save the list, with exact versions, you use a file called requirements.txt:

python -m pip freeze > requirements.txt

On another computer, or on the server, just create a new virtual environment, activate it and install everything with a single command:

python -m pip install -r requirements.txt

The requirements.txt file should be kept together with the project code. The .venv folder, on the other hand, should not be copied or added to Git: it contains paths tied to your computer and can be recreated in a few seconds. If you use Git, add this line to the .gitignore file:

.venv/

Deactivating and deleting an environment

To leave the virtual environment, just type:

deactivate

To delete it completely, simply remove the .venv folder. There is nothing to uninstall: everything it contained was in there.

This is also useful when you want to change the Python version of a project: delete the folder, recreate the environment with the new version and reinstall the dependencies from requirements.txt.

Using the environment with Visual Studio Code

If you use Visual Studio Code with the Python extension, the editor usually recognises the .venv folder on its own. If it does not, open the command palette with Ctrl+Shift+P, search for Python: Select Interpreter and choose the interpreter inside .venv. From then on, the integrated terminal will also activate the environment automatically.

Common errors and solutions

  • “ModuleNotFoundError: No module named …”: almost always the environment is not active, or the library was installed into another Python. Activate the environment and reinstall the library with python -m pip install.
  • “error: externally-managed-environment” on Linux: you are trying to install a library into the system Python. Create and activate a virtual environment and repeat the installation inside it.
  • “The virtual environment was not created successfully because ensurepip is not available” on Ubuntu or Debian: the python3-venv package is missing. Install it with sudo apt install python3-venv, delete the incomplete .venv folder and recreate the environment.
  • The environment stops working after moving or renaming the project folder: virtual environments contain absolute paths and do not survive being moved. Delete it and recreate it.
  • “Microsoft Visual C++ 14.0 or greater is required” error while installing a library: usually the environment was created with a Python version that is too recent for that library. We have devoted an article to this error.

A look at alternative tools

Besides venv there are more complete tools, such as uv or Poetry, which manage environments, dependencies and Python versions all in one go. They are very popular in larger projects. To get started, though, venv is the best choice: it is already included in Python, it works everywhere, and the concepts you have learned here also apply to the other tools.

Summary

The workflow of every Python project comes down to a few commands:

  • Once: python -m venv .venv in the project folder.
  • Every time you work on the project: activate the environment.
  • To add libraries: python -m pip install name, then update requirements.txt.
  • On another computer: create the environment, activate it and run python -m pip install -r requirements.txt.

Official sources

Share

What's Your Reaction?

Like Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0