When working with Python, it’s easy to install a package whenever your application needs it. A quick pip install, and you’re ready to go.
But what happens when another project needs a different version of that same package? Or when an update breaks an application that was working perfectly fine yesterday?
This is where Python virtual environments come in.
A virtual environment gives each project its own isolated Python environment, including its own installed packages. Instead of having every project depend on the same collection of globally installed packages, each application can maintain the versions it needs without interfering with other projects.
In this article, we’ll look at what virtual environments are, why they matter, and how to create and use one in a Python project.
What Is a Python Virtual Environment?
A Python virtual environment is an isolated environment created for a specific project. It provides its own package installation location and Python executable, allowing the project to manage its dependencies independently of other applications.
Python includes a built-in module called venv for creating these environments. There is no need to install another package or use an external tool to get started.
For example, imagine you have two Python applications:
- Project A uses SQLAlchemy 1.4.
- Project B uses SQLAlchemy 2.0.
Without separate environments, installing or upgrading packages globally can create version conflicts. Updating SQLAlchemy for one application could potentially break the other.
With virtual environments, each project has its own installation of SQLAlchemy. Project A can continue using version 1.4 while Project B uses version 2.0.
Neither project needs to interfere with the other.
Creating a Virtual Environment
Creating a virtual environment is straightforward. I generally create it directly inside the application’s project directory.
First, open a terminal and navigate to your project:
cd /path/to/your/project
Next, run:
python -m venv venv
The first venv is the Python module used to create the environment. The second venv is the name of the directory where the environment will be created.
You can name this directory something else, such as .venv, but I typically use venv.
After running the command, Python creates the environment directory and its supporting files.
The directory structure will look something like this:
my-project/ │ ├── venv/ │ ├── bin/ │ ├── lib/ │ └── pyvenv.cfg │ └── application.py
This is a simplified example of the directory structure on macOS or Linux. Windows uses a slightly different layout, which we’ll cover when activating the environment.
A note about the Python command: Depending on your operating system and installation, you may need to use python3 instead of python:
python3 -m venv venv
The important thing is to use the Python interpreter you intend to use for the project.
Activating the Virtual Environment
Creating the environment is only the first step. Before installing packages, you need to activate it.
The activation command depends on your operating system and the terminal you’re using.
macOS and Linux
From the project directory, run:
source venv/bin/activate
Windows Command Prompt
venv\Scripts\activate.bat
Windows PowerShell
.\venv\Scripts\Activate.ps1
Once activated, your terminal prompt will typically display the environment name in parentheses.
For example:
(venv) user@computer my-project %
That (venv) indicator is a helpful visual reminder that the environment is active.
If you’re finished working in the environment, you can deactivate it by running:
deactivate
This returns your terminal session to its normal Python environment. It does not delete the virtual environment or any packages installed inside it.
Installing Packages Inside the Environment
Once the virtual environment is activated, you can install packages just as you normally would.
For example:
python -m pip install sqlalchemy
Using python -m pip ensures that pip is associated with the Python interpreter currently being used. This helps avoid accidentally installing a package into a different Python installation.
If you want to install a specific version, you can specify it:
python -m pip install "SQLAlchemy==2.0.44"
The package will be installed inside the active virtual environment rather than the global Python package directory.
You can verify which pip installation is being used with:
python -m pip --version
The output includes the location of the pip installation. When the virtual environment is active, that path should point inside your project’s venv directory.
This is particularly useful when troubleshooting package installation issues or when you have multiple Python installations on the same machine.
How Does the Isolation Work?
When you activate a virtual environment, your shell adjusts its executable search path so that the environment’s Python and package-management tools are found before the global ones.
In practical terms, commands such as python and pip now resolve to the executables associated with your virtual environment.
The environment also has its own package installation directory. On macOS and Linux, installed packages are typically stored under:
venv/lib/pythonX.Y/site-packages/
On Windows, the corresponding location is generally:
venv\Lib\site-packages\
The X.Y portion represents the Python version.
This means packages installed in one virtual environment are separate from packages installed in another environment.
For example, if Project A installs SQLAlchemy 1.4 and Project B installs SQLAlchemy 2.0, each project uses the version installed in its own environment.
An update or removal of a package in one environment does not normally affect the other environment or your global Python packages.
This isolation is one of the biggest reasons to use virtual environments. You can update, remove, or experiment with dependencies without unnecessarily risking other applications.
Managing Multiple Projects
Once you start using virtual environments, the workflow becomes fairly simple.
Each project gets its own environment, and you activate the appropriate one when working on that application.
For example:
projects/
│
├── project-a/
│ ├── venv/
│ └── application.py
│
└── project-b/
├── venv/
└── application.py
When working on Project A, activate its environment:
cd project-a source venv/bin/activate
When you’re ready to work on Project B, deactivate the first environment and activate the second:
deactivate cd ../project-b source venv/bin/activate
The activation commands shown here are for macOS and Linux. Use the appropriate Windows command if you’re working in Command Prompt or PowerShell.
Each project now has its own independent package installation area.
This approach also makes it easier to test different package versions, troubleshoot dependency problems, and maintain applications that may not all use the same Python libraries.
Should You Copy or Commit Your Virtual Environment?
One question that often comes up is whether the virtual environment directory should be copied to another machine or included in source control.
Generally, no.
A virtual environment can contain a large number of files, including installed packages and references to the Python installation used to create it. Those files can be specific to the operating system, Python version, and machine where the environment was created.
Copying the directory to another computer is not a reliable way to recreate the same environment. It can also unnecessarily increase the size of a project repository.
Instead, keep the environment directory out of source control and recreate it when setting up the project on another machine.
This raises another important question: if we don’t copy the environment, how do we tell Python which packages the application needs?
That’s where requirements.txt comes in.
Final Thoughts
Python virtual environments are a simple but important part of maintaining Python applications.
They help prevent dependency conflicts, keep project packages isolated, and reduce the risk of one application’s changes affecting another. They also give you a cleaner way to experiment with package updates without disturbing your other projects.
Creating an environment takes only a few seconds, and once it becomes part of your normal workflow, it’s easy to forget what working without one was like.
In the next article, we’ll look at requirements.txt, how to document project dependencies, and how to recreate an application’s package environment without having to figure everything out from scratch.
Leave a Reply