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.
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-venvpackage is missing. Install it withsudo apt install python3-venv, delete the incomplete.venvfolder 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 .venvin the project folder. - Every time you work on the project: activate the environment.
- To add libraries:
python -m pip install name, then updaterequirements.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
0
Dislike
0
Love
0
Funny
0
Angry
0
Sad
0
Wow
0