Python Virtual Environments: A Practical Guide with venv and pip

Installing Python packages globally can become a problem surprisingly quickly.

One project may need one version of a library while another project needs a different version. Without isolation, changing one project can accidentally affect another.

Python virtual environments solve this problem by giving each project its own isolated Python environment.

In this guide, you'll learn how to create and use virtual environments with Python's built-in venv module, install packages with pip, manage dependencies, configure VS Code, and troubleshoot common problems.

Quick answer: Create a virtual environment with python -m venv .venv, activate it, install packages with pip, and keep .venv out of Git.

Python Virtual Environments at a Glance

Task	Command
Create environment	`python -m venv .venv`
Activate on Windows	`.venv\Scripts\activate`
Activate on macOS/Linux	`source .venv/bin/activate`
Install package	`python -m pip install requests`
List packages	`python -m pip list`
Save dependencies	`python -m pip freeze > requirements.txt`
Install dependencies	`python -m pip install -r requirements.txt`
Leave environment	`deactivate`
Check Python	`python --version`
Check pip	`python -m pip --version`

The Python Packaging User Guide recommends using virtual environments when working with third-party packages.

oaicite

Why Do Python Projects Need Virtual Environments?

Imagine you have two projects.

Project A

text

Project A
└── Django 4.x

Project B

text

Project B
└── Django 5.x

If both projects depend on packages installed into the same global Python environment, changing dependencies for one project can create problems for the other.

A virtual environment gives each project its own package installation location.

Diagram / Architecture

The environments use a base Python installation while keeping their project packages isolated.

oaicite

What Is a Virtual Environment?

A virtual environment is an isolated Python environment created for a specific project.

It contains its own:

Python executable
installed packages
package installation location
environment configuration

For example:

text

my-project/
├── .venv/
├── app.py
├── requirements.txt
└── README.md

The .venv directory belongs to the development environment, not your application source code.

Python's documentation recommends treating virtual environments as disposable and recreating them when necessary rather than moving or copying them between systems.

oaicite

Creating Your First Virtual Environment

First, create a project directory.

bash

mkdir python-demo
cd python-demo

Now create the environment.

Windows

powershell

py -m venv .venv

macOS/Linux

bash

python3 -m venv .venv

You can also use:

bash

python -m venv .venv

The command creates a .venv directory containing the environment.

Activating the Environment

Creating the environment is not enough.

You normally activate it before installing and using project dependencies.

Windows PowerShell

powershell

.venv\Scripts\Activate.ps1

Windows Command Prompt

cmd

.venv\Scripts\activate

macOS/Linux

bash

source .venv/bin/activate

After activation, your terminal usually shows the environment name:

text

(.venv) C:\projects\python-demo>

Now package installations go into that environment.

The official packaging guide documents these activation commands for Windows and Unix-like systems.

oaicite

Verify the Environment

After activation, check Python:

bash

python --version

Then check where Python is coming from.

Windows

powershell

where python

macOS/Linux

bash

which python

You should see a path associated with your .venv.

For example:

text

python-demo\.venv\Scripts\python.exe

This confirms that your project is using the virtual environment's interpreter.

Installing Packages with pip

Once the environment is active, you can install packages.

For example:

bash

python -m pip install requests

You can verify the installation:

bash

python -m pip show requests

Or list installed packages:

bash

python -m pip list

Example:

text

Package    Version
---------- -------
pip        ...
requests   ...

Using:

bash

python -m pip

is useful because it makes it explicit that pip is being executed through the Python interpreter you're currently using.

Installing Multiple Packages

Suppose you're building a small API.

You might install:

bash

python -m pip install fastapi uvicorn

Now your environment contains:

text

.venv
├── fastapi
├── uvicorn
└── dependencies...

Your global Python installation does not need those project-specific packages.

Understanding requirements.txt

A common way to describe Python dependencies is a requirements.txt file.

For example:

text

fastapi
uvicorn
requests

You can install them with:

bash

python -m pip install -r requirements.txt

You can also generate a requirements file from an existing environment:

bash

python -m pip freeze > requirements.txt

Then another developer can recreate the environment:

bash

python -m pip install -r requirements.txt

This creates a simple dependency workflow:

Diagram / Architecture

A Complete Python Project Setup

A typical beginner project might look like this:

text

weather-api/
├── .venv/
├── app.py
├── requirements.txt
├── .gitignore
└── README.md

Create the environment:

bash

python -m venv .venv

Activate it.

Install dependencies:

bash

python -m pip install requests

Create your application:

python

import requests

response = requests.get("https://example.com")

print(response.status_code)

Save the dependency list:

bash

python -m pip freeze > requirements.txt

Now the project contains both the source code and a description of its Python dependencies.

Never Commit .venv to Git

Your virtual environment should normally not be committed to Git.

Add this to .gitignore:

gitignore

.venv/
venv/
__pycache__/
*.pyc

Why?

Because .venv contains environment-specific files and installed packages.

Instead of committing the environment itself, commit the files needed to recreate it:

text

.gitignore
requirements.txt
app.py
README.md

Python's current documentation explicitly notes that virtual environments should not be checked into source control.

oaicite

Recreating an Environment on Another Computer

Imagine your project is stored on GitHub.

Another developer clones it:

bash

git clone https://github.com/example/python-project.git
cd python-project

They create a new environment:

bash

python -m venv .venv

Activate it.

Then install the dependencies:

bash

python -m pip install -r requirements.txt

The environment is recreated without committing .venv.

Diagram / Architecture

This is much more portable than sharing the virtual environment directory itself.

How pip and venv Work Together

They solve different problems.

Tool	Purpose
Python	Runs Python programs
venv	Creates isolated environments
pip	Installs Python packages
requirements.txt	Records dependencies
Git	Tracks project source code

A useful mental model is:

text

Python
  ↓
venv
  ↓
Project Environment
  ↓
pip
  ↓
Packages
  ↓
Application

Updating pip

You can check your pip version:

bash

python -m pip --version

You can upgrade pip with:

Windows

powershell

py -m pip install --upgrade pip

macOS/Linux

bash

python3 -m pip install --upgrade pip

The Python Packaging User Guide documents these commands for supported Python environments.

oaicite

Installing a Specific Package Version

Sometimes a project requires a particular version.

For example:

bash

python -m pip install requests==2.32.5

You can also specify a minimum version:

bash

python -m pip install "requests>=2.30"

Or a version range:

bash

python -m pip install "requests>=2.30,<3"

This becomes important when applications depend on specific library behavior.

Checking Installed Packages

Use:

bash

python -m pip list

For detailed information:

bash

python -m pip show requests

To check outdated packages:

bash

python -m pip list --outdated

Be careful about upgrading dependencies blindly in production projects.

A package update can introduce breaking changes.

Deactivating a Virtual Environment

When you're finished:

bash

deactivate

Your terminal returns to the normal Python environment.

You can activate the same environment again later.

bash

source .venv/bin/activate

or on Windows:

powershell

.venv\Scripts\activate

You do not need to recreate the environment every time you open the project.

Deleting and Recreating a Virtual Environment

Virtual environments are designed to be disposable.

If an environment becomes corrupted, you can remove it and recreate it.

Windows

powershell

Remove-Item -Recurse -Force .venv

macOS/Linux

bash

rm -rf .venv

Then:

bash

python -m venv .venv

Activate it:

bash

source .venv/bin/activate

Install dependencies:

bash

python -m pip install -r requirements.txt

This is often much cleaner than trying to repair a broken environment manually.

VS Code and Python Virtual Environments

VS Code can detect Python environments inside your project.

A common structure is:

text

project/
├── .venv/
├── src/
├── requirements.txt
└── README.md

After opening the project in VS Code, select the Python interpreter associated with .venv.

The important part is that your editor, terminal, testing tools, and application should use the same environment.

Common Problem: pip Installs Into the Wrong Python

You run:

bash

pip install requests

but your application says:

text

ModuleNotFoundError: No module named 'requests'

One possible cause is that pip and python point to different installations.

Check:

bash

python --version
python -m pip --version

On Windows:

powershell

where python
where pip

On macOS/Linux:

bash

which python
which pip

Using:

bash

python -m pip install requests

helps ensure the package is installed for the Python interpreter you're actually using.

Common Problem: Environment Is Not Activated

You create:

bash

python -m venv .venv

and immediately run:

bash

pip install requests

You may accidentally install the package outside your project environment.

Activate the environment first:

bash

source .venv/bin/activate

Then:

bash

python -m pip install requests

Common Problem: PowerShell Blocks Activation

On some Windows configurations, PowerShell can block script execution.

If activation fails, you may see an execution-policy-related message.

You can use Command Prompt instead:

cmd

.venv\Scripts\activate

Or review your PowerShell execution-policy configuration according to your organization's security requirements.

Do not blindly disable security controls just to activate a Python environment.

Common Problem: Python Command Is Not Found

If this fails:

bash

python --version

try:

bash

python3 --version

On Windows, the Python launcher may also work:

powershell

py --version

Then create the environment with:

powershell

py -m venv .venv

Common Problem: Linux Says the Environment Cannot Be Created

Some Linux distributions manage system Python installations externally.

Modern Python packaging specifications can mark an interpreter as externally managed and guide users toward virtual environments rather than modifying the system installation.

oaicite

For a project environment, try:

bash

python3 -m venv .venv

If your distribution reports that the required venv support is missing, install the appropriate distribution package according to your Linux distribution's documentation.

Virtual Environment vs Global Installation

Approach	Global Install	Virtual Environment
Project isolation	❌	✅
Different dependency versions	Difficult	Easy
Safer project setup	❌	✅
Reproducible development	Limited	Better
Easy cleanup	❌	✅
Recommended for third-party project packages	Usually not	✅

The main advantage is isolation.

Virtual Environment vs virtualenv

You may see both venv and virtualenv.

venv

venv is included in modern Python and is part of Python's standard library.

bash

python -m venv .venv

virtualenv

virtualenv is a separate third-party tool.

bash

python -m pip install virtualenv

Then:

bash

python -m virtualenv .venv

For many normal application projects, the built-in venv module is enough.

Virtual Environments in AI and Data Science

Virtual environments become particularly useful in AI and data projects.

One project might use:

text

Project A
Python libraries
├── numpy
├── pandas
└── scikit-learn

Another might use:

text

Project B
Python libraries
├── numpy
├── pandas
└── torch

Different projects can evolve independently.

This is especially useful when experimenting with machine learning libraries, APIs, notebooks, and different dependency versions.

Virtual Environments in Backend Development

Python backend projects frequently have multiple dependencies.

For example:

text

FastAPI
Uvicorn
SQLAlchemy
PostgreSQL driver
Pydantic

A project environment keeps those dependencies associated with the application instead of installing everything globally.

A typical workflow becomes:

bash

mkdir backend-api
cd backend-api

python -m venv .venv

Activate:

bash

source .venv/bin/activate

Install:

bash

python -m pip install fastapi uvicorn

Save dependencies:

bash

python -m pip freeze > requirements.txt

A Better Daily Python Workflow

A practical workflow looks like this:

Diagram / Architecture

For a new project:

bash

mkdir my-project
cd my-project

python -m venv .venv

Activate it.

Then:

bash

python -m pip install requests

Work on your application.

Finally:

bash

python -m pip freeze > requirements.txt

Commit:

text

app.py
requirements.txt
.gitignore
README.md

Do not commit:

text

.venv/

Best Practices

1. Use one environment per project

text

project-a/.venv
project-b/.venv
project-c/.venv

This keeps dependencies isolated.

2. Use `.venv` as the directory name

It is easy to recognize and works well with modern development tools.

3. Do not commit `.venv`

Keep it in .gitignore.

4. Record dependencies

For projects using requirements.txt:

bash

python -m pip freeze > requirements.txt

5. Verify your interpreter

When debugging dependency problems, check:

bash

python -m pip --version

6. Recreate broken environments

Don't spend hours repairing a badly corrupted environment.

Delete and recreate it when appropriate.

7. Keep development and production concerns separate

A local virtual environment is useful for development, but production deployment may use containers, system packaging, or other deployment mechanisms depending on the application.

The Python Packaging User Guide specifically distinguishes development virtual environments from broader production packaging and deployment approaches.

oaicite

Mini Project: Build a Python Dependency Demo

Let's create a small project to practice everything.

Step 1: Create the project

bash

mkdir dependency-demo
cd dependency-demo

Step 2: Create the environment

bash

python -m venv .venv

Step 3: Activate it

Windows:

powershell

.venv\Scripts\activate

macOS/Linux:

bash

source .venv/bin/activate

Step 4: Install Requests

bash

python -m pip install requests

Step 5: Create app.py

python

import requests

url = "https://example.com"

response = requests.get(url, timeout=10)

print("Status:", response.status_code)

Step 6: Run it

bash

python app.py

Step 7: Save dependencies

bash

python -m pip freeze > requirements.txt

Step 8: Add Git ignore

Create .gitignore:

gitignore

.venv/
__pycache__/
*.pyc

You now have a basic Python project with an isolated development environment.

Understanding the Mental Model

The easiest way to remember everything is:

text

Python
  │
  ├── Base installation
  │
  └── Project
        │
        └── .venv
              │
              ├── Python
              ├── pip
              └── Project packages

Your source code lives outside .venv.

Your environment contains the dependencies required to run that source code.

Your Git repository stores the project and dependency instructions, not the environment itself.

Python Environment Cheat Sheet

Create

bash

python -m venv .venv

Activate — Windows

powershell

.venv\Scripts\activate

Activate — macOS/Linux

bash

source .venv/bin/activate

Install

bash

python -m pip install package-name

Uninstall

bash

python -m pip uninstall package-name

List packages

bash

python -m pip list

Save dependencies

bash

python -m pip freeze > requirements.txt

Install dependencies

bash

python -m pip install -r requirements.txt

Check Python

bash

python --version

Check pip

bash

python -m pip --version

Deactivate

bash

deactivate

Common Mistakes to Avoid

Installing everything globally

bash

pip install package1 package2 package3

This can make unrelated projects depend on the same environment.

Prefer a project-specific virtual environment.

Committing `.venv`

Don't push the entire environment to Git.

Use:

gitignore

.venv/

Using the wrong interpreter

If your package is installed but Python cannot import it, check which Python and pip you're using.

Copying `.venv` between computers

Virtual environments are not designed to be portable copies.

Create a new environment and reinstall the dependencies.

Forgetting dependency management

A project that works only on one developer's computer is difficult to maintain.

Keep dependency information in the repository.

Why This Matters for Developers

Virtual environments are a small Python concept, but they become extremely important as your projects grow.

They help with:

Backend development
Data science
Machine learning
Automation
APIs
Web applications
Testing
CLI applications
AI applications
Open-source projects

If you're learning Python professionally, understanding environments, packages, and dependencies should be part of your core workflow.

Interview Questions

1. What is a Python virtual environment?

An isolated Python environment that allows a project to use its own interpreter context and installed packages without mixing them with other project environments.

2. What command creates a virtual environment?

bash

python -m venv .venv

3. Why shouldn't `.venv` be committed to Git?

It contains environment-specific files and installed packages and should be recreated from project dependency information instead.

4. What is pip?

pip is the standard Python package installer used to install and manage Python packages.

5. What is requirements.txt?

A file commonly used to record Python project dependencies so they can be installed into another environment.

6. How do you install requirements?

bash

python -m pip install -r requirements.txt

7. How do you deactivate a virtual environment?

bash

deactivate

8. Why use `python -m pip` instead of simply `pip`?

It helps ensure that pip is executed through the Python interpreter you're currently using, reducing confusion when multiple Python installations exist.

FAQ

Do I need a virtual environment for every Python project?

For projects using third-party dependencies, using a separate virtual environment is a strong default because it keeps dependencies isolated.

Is `.venv` part of my application?

No. It is the project's local Python environment.

Should `.venv` be uploaded to GitHub?

No. Add it to .gitignore.

Can I delete `.venv`?

Yes. Virtual environments are designed to be disposable.

Do I need to recreate `.venv` every time I open VS Code?

No. Once created, you normally reactivate or select the existing environment.

Is venv a Python package?

No. venv is part of Python's standard library.

Can multiple projects use the same virtual environment?

They technically can, but separate environments are generally better because each project can have independent dependencies.

Final Takeaway

Python virtual environments are one of the simplest ways to keep projects clean and predictable.

The essential workflow is:

text

Create project
     ↓
Create .venv
     ↓
Activate .venv
     ↓
Install packages with pip
     ↓
Develop and test
     ↓
Record dependencies
     ↓
Commit source code

The commands worth remembering are:

bash

python -m venv .venv
python -m pip install package-name
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
deactivate

Once you understand this workflow, starting a new Python backend, automation, AI, or data project becomes much more predictable.

Learn the environment before the dependencies—and your Python projects become much easier to manage.

Python Virtual Environments: A Practical Guide with venv and pip

Python Virtual Environments: A Practical Guide with venv and pip

Python Virtual Environments at a Glance

Why Do Python Projects Need Virtual Environments?

Project A

Project B

What Is a Virtual Environment?

Creating Your First Virtual Environment

Windows

macOS/Linux

Activating the Environment

Windows PowerShell

Windows Command Prompt

macOS/Linux

Verify the Environment

Windows

macOS/Linux

Installing Packages with pip

Installing Multiple Packages

Understanding requirements.txt

A Complete Python Project Setup

Never Commit .venv to Git

Recreating an Environment on Another Computer

How pip and venv Work Together

Updating pip

Windows

macOS/Linux

Installing a Specific Package Version

Checking Installed Packages

Deactivating a Virtual Environment

Deleting and Recreating a Virtual Environment

Windows

macOS/Linux

VS Code and Python Virtual Environments

Common Problem: pip Installs Into the Wrong Python

Common Problem: Environment Is Not Activated

Common Problem: PowerShell Blocks Activation

Common Problem: Python Command Is Not Found

Common Problem: Linux Says the Environment Cannot Be Created

Virtual Environment vs Global Installation

Virtual Environment vs virtualenv

venv

virtualenv

Virtual Environments in AI and Data Science

Virtual Environments in Backend Development

A Better Daily Python Workflow

Best Practices

1. Use one environment per project

2. Use .venv as the directory name

3. Do not commit .venv

4. Record dependencies

5. Verify your interpreter

6. Recreate broken environments

7. Keep development and production concerns separate

Mini Project: Build a Python Dependency Demo

Step 1: Create the project

Step 2: Create the environment

Step 3: Activate it

Step 4: Install Requests

Step 5: Create app.py

Step 6: Run it

Step 7: Save dependencies

Step 8: Add Git ignore

Understanding the Mental Model

Python Environment Cheat Sheet

Create

Activate — Windows

Activate — macOS/Linux

Install

Uninstall

List packages

Save dependencies

Install dependencies

Check Python

Check pip

Deactivate

Common Mistakes to Avoid

Installing everything globally

Committing .venv

Using the wrong interpreter

2. Use `.venv` as the directory name

3. Do not commit `.venv`

Committing `.venv`

Copying `.venv` between computers

3. Why shouldn't `.venv` be committed to Git?

8. Why use `python -m pip` instead of simply `pip`?

Is `.venv` part of my application?

Should `.venv` be uploaded to GitHub?

Can I delete `.venv`?

Do I need to recreate `.venv` every time I open VS Code?