# What is a Virtual Environment?

A virtual environment is an isolated Python runtime that keeps a project's packages separate from every other project on the machine. Each environment has its own `site-packages` directory, so package installations never spill across project boundaries or touch [the system Python](https://pydevtools.com/handbook/explanation/why-should-i-avoid-system-python.md).

Installing packages into a shared Python creates three problems that compound as the number of projects grows:

- **Version conflicts.** Different projects often require different versions of the same library. Without isolation, the last install wins and earlier projects silently break.
- **Dependency pollution.** Every project sharing one interpreter makes it impossible to track which packages belong to which project, or to reproduce the environment on another machine.
- **System integrity risk.** On macOS and Linux, the system Python runs internal OS tools. Overwriting a package it depends on can break those tools without warning.

## How activation works

Creating a virtual environment does not change anything by itself. Activating it rewrites the shell's `PATH` so that the environment's `python` and `pip` take precedence over the system installation. The command depends on the platform and shell:

```bash
source .venv/bin/activate
```
```powershell
.venv\Scripts\Activate.ps1
```
After activation, the shell prompt usually changes to show the environment name in parentheses, and running [`pip`](https://pydevtools.com/handbook/reference/pip.md) or `python` invokes the environment's copies. Running `deactivate` restores the original shell.

## What isolation looks like in practice

A short console session makes the abstract idea of isolation concrete. On macOS or Linux:

```console
$ which python
/usr/bin/python

$ python -m venv .venv
$ source .venv/bin/activate

(.venv) $ which python
/path/to/project/.venv/bin/python

(.venv) $ pip install cowsay
(.venv) $ python -c "import cowsay; print(cowsay.__file__)"
/path/to/project/.venv/lib/python3.14/site-packages/cowsay/__init__.py

(.venv) $ deactivate
$ python -c "import cowsay"
ModuleNotFoundError: No module named 'cowsay'
```

Inside the environment, `cowsay` imports from a file inside `.venv/`. Outside, the import fails entirely. Nothing was written to the system Python, and a second project can maintain its own independent set of packages without touching this one.

## Let uv manage environments automatically

[uv](https://pydevtools.com/handbook/reference/uv.md) creates and activates virtual environments implicitly, removing the manual create-and-activate cycle. The traditional workflow, built on Python's standard-library [venv](https://pydevtools.com/handbook/reference/venv.md) module, takes four steps:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

`uv run main.py` handles all four. uv creates `.venv` if it doesn't exist, installs dependencies from `pyproject.toml`, and runs the script without an explicit activation step.

## Learn More

* [How to create and use a Python virtual environment with venv](https://pydevtools.com/handbook/how-to/how-to-create-and-use-a-python-virtual-environment-with-venv.md) walks through the create / activate / install / deactivate lifecycle step by step.
* [How to configure Claude Code to use virtual environments](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-to-use-virtual-environments.md) shows how AI assistants can respect project-level isolation.
* [Why should I use a virtual environment?](https://pydevtools.com/handbook/explanation/why-should-i-use-a-virtual-environment.md)
* [How to require a virtualenv when installing packages with pip](https://pydevtools.com/handbook/how-to/how-to-require-a-virtual-for-installing-packages.md)
* [How to customize uv's virtual environment location](https://pydevtools.com/handbook/how-to/how-to-customize-uvs-virtual-environment-location.md)
* [venv reference: venv vs virtualenv vs uv](https://pydevtools.com/handbook/reference/venv.md) compares the three tools and answers whether venv is deprecated.
* [virtualenv](https://pydevtools.com/handbook/reference/virtualenv.md) reference