# How to create and use a Python virtual environment with venv

A README says "create a virtual environment" before it tells you what that means. Use Python's built-in [`venv`](https://pydevtools.com/handbook/reference/venv.md) module to create one, activate it, and install packages into the right place. For the concepts, see [What is a virtual environment?](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md). For a new project from scratch, [uv](https://pydevtools.com/handbook/reference/uv.md) handles all of this for you.

## Create the environment

Run this from your project directory:

```bash
python3 -m venv .venv
```
```powershell
py -m venv .venv
```

If Windows does not recognize `py`, use `python -m venv .venv` instead.
This creates a `.venv/` folder containing its own Python interpreter and `site-packages/` directory. The leading dot keeps the folder hidden from most file listings, and most tools recognize `.venv` as the default environment location. Add it to `.gitignore` so the environment stays out of source control.

> [!NOTE]
> On Debian or Ubuntu, the system `python3` package does not include the `ensurepip` module that `venv` requires. If `python3 -m venv` fails with "ensurepip is not available," run `sudo apt install python3-venv` first.

## Activate it on your platform

Activation rewrites the shell's `PATH` so `python` and [`pip`](https://pydevtools.com/handbook/reference/pip.md) resolve to the environment's copies.

For bash or zsh:

```bash
source .venv/bin/activate
```

For fish:

```bash
source .venv/bin/activate.fish
```
For PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

If PowerShell refuses with "running scripts is disabled on this system," run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once, then try activation again.

For the older Command Prompt:

```powershell
.venv\Scripts\activate.bat
```
The shell prompt usually prefixes with `(.venv)` once activation succeeds. Running `which python` on macOS/Linux or `where.exe python` on Windows should now point inside `.venv/`.

## Install packages

Install a single package:

```bash
pip install requests
```

Install everything a [`requirements.txt`](https://pydevtools.com/handbook/reference/requirements.md) lists:

```bash
pip install -r requirements.txt
```

Snapshot the current environment back out to a file:

```bash
pip freeze > requirements.txt
```

## Run Python and scripts

While the environment is active, `python` uses the venv's interpreter and imports the venv's packages:

```bash
python main.py
python -m pytest
python
```

`python -m pytest` runs [pytest](https://pydevtools.com/handbook/reference/pytest.md) against your project, and a bare `python` opens an interactive REPL with the installed packages available.

## Deactivate when you're done

```bash
deactivate
```

This restores the original `PATH`. The environment still exists on disk; activate it again to pick up where you left off.

## Start fresh if the environment breaks

A broken environment is disposable. Delete and recreate it:

```bash
deactivate  # if active
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
```powershell
deactivate  # if active
Remove-Item -Recurse -Force .venv
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
If there is no `requirements.txt`, you have to reinstall whatever packages the project needs by hand. That's one reason a [lockfile](https://pydevtools.com/handbook/explanation/what-is-a-lock-file.md) matters for reproducible builds.

## Skip all this with uv

For a new project, [uv](https://pydevtools.com/handbook/reference/uv.md) replaces this entire lifecycle with one command:

```bash
uv run main.py
```

uv creates the virtual environment, installs dependencies from [`pyproject.toml`](https://pydevtools.com/handbook/reference/pyproject.toml.md), and runs the script in one shot. There's no activation step and no "did I install this in the right env?" guessing.

[Run your first Python script with uv](https://pydevtools.com/handbook/tutorial/how-to-run-your-first-python-script.md) is the fastest starting point, and [Create your first Python project with uv](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md) scaffolds a full project from scratch. If you already have a `requirements.txt`, [migrate it to pyproject.toml with uv](https://pydevtools.com/handbook/how-to/migrate-requirements.txt.md) in a few steps.

## Learn More

- [What is a virtual environment?](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) explains what the `.venv` directory actually contains and how isolation works.
- [Why should I use a virtual environment?](https://pydevtools.com/handbook/explanation/why-should-i-use-a-virtual-environment.md) covers the problems virtual environments solve.
- [venv reference](https://pydevtools.com/handbook/reference/venv.md) documents every venv flag and edge case.
- [How to fix the "externally-managed-environment" error](https://pydevtools.com/handbook/how-to/how-to-fix-the-externally-managed-environment-error.md) handles the [PEP 668](https://pydevtools.com/handbook/explanation/what-is-pep-668.md) block you may have hit before landing here.