When working on multiple Python projects, you might face a situation like this: “Project A needs Library X version 1.0, but Project B needs version 2.0.” If you only have one system-wide Python installation, these dependency conflicts become a major problem.
The solution is a Virtual Environment. A virtual environment provides an isolated Python execution environment (a separate place to install libraries) for each project. The venv module has been a standard part of Python since version 3.3, so you can use it without installing anything extra.
This article explains how to create, activate, and deactivate virtual environments using venv.
What is a Virtual Environment?
A virtual environment is an “isolated” Python environment dedicated to a specific project. Packages (libraries) installed inside this environment do not affect other projects or your system-wide Python installation.
Key Benefits:
- Dependency Separation: You can manage different versions of packages for each project.
- Reproducibility: Combined with
pip freeze, you can exactly reproduce the same environment on other developers’ machines or production servers. - Clean System: You avoid cluttering your main system Python environment.
Creating a Virtual Environment
To create a virtual environment, run the command python -m venv followed by the name you want to give the environment. Here, we will create an environment named project_env.
# Creates a directory named 'project_env'
python -m venv project_env
Running this command creates a folder named project_env in your current directory. It contains the Python executable and subdirectories (like bin, Scripts, or lib) for managing packages.
Activating the Virtual Environment
Just creating the environment isn’t enough; you need to “Activate” it to enter it. The activation command depends on your OS and shell.
Once activated, the environment name (e.g., (project_env)) will appear at the start of your terminal prompt.
1. Windows (Command Prompt)
Run the .bat file.
:: Assuming you are in the current directory
project_env\Scripts\activate
2. Windows (PowerShell)
Run the .ps1 script.
# Assuming you are in the current directory
.\project_env\Scripts\Activate.ps1
Note on PowerShell Execution Policy: If you get a security error, it might be due to PowerShell’s execution policy. You can allow script execution for the current process by running this command, then try activating again:
Set-ExecutionPolicy RemoteSigned -Scope Process
3. macOS / Linux (bash/zsh)
Use the source command.
# Assuming you are in the current directory
source project_env/bin/activate
Deactivating the Virtual Environment
When you are done working and want to return to the original system environment, run the following command. This is the same for all operating systems.
deactivate
Once run, the environment name (project_env) will disappear from your prompt, indicating you are back in the normal terminal state.
Managing Packages in a Virtual Environment
When the virtual environment is active, using the pip command installs packages only inside that virtual environment.
# Run this while (project_env) is displayed
pip install requests
# Only 'requests' installed in project_env will be shown
pip freeze
Summary
venv is an essential tool for maintaining a clean and reproducible Python development environment.
- Create:
python -m venv <env_name> - Activate: Run the activate script (path differs by OS).
- Deactivate: Run
deactivate.
I recommend making it a habit to create and activate a venv virtual environment every time you start a new project.
