---
title: "Use pip and a virtual environment for · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/languages-and-runtimes/pip-and-venv
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use pip and a virtual environment for Python packages

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Languages and runtimes](https://agentwranglers.se/playbook/stack/languages-and-runtimes.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- Level: Recommended
- Chapter: [Languages and runtimes](https://agentwranglers.se/playbook/stack/languages-and-runtimes)
- Rule: Install Python packages with pip into a virtual environment per project, from a file that pins every version.
- Cost: Open source. MIT licence, and the Python Package Index is free to use.
- How: pip passes all five tests. Its first release was in October 2008, and 26.2.2 shipped on 20 October 2026. It had 105 million downloads in the week to 20 October 2026. In the Stack Overflow Developer Survey 2026, 42.1% of developers used it. It is MIT licensed. The `venv` module ships with Python, so nothing else needs installing. Choose something else when installs are slow or you want a lock file built in, where uv is fast and popular. uv fails the five-year test, since its first release was in February 2024 and it is still version 0.13. Record that choice in a decision record. Pin every version, as [Make builds repeatable](https://agentwranglers.se/playbook/engineering/running-in-production/reproducible-builds) says.
- Check: The project has a `.venv` folder that is not committed. `requirements.txt` pins every package with `==`. Every build runs `pip install -r requirements.txt` inside the virtual environment.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
python3.14 -m venv .venv
.venv/bin/pip install django
.venv/bin/pip freeze > requirements.txt
.venv/bin/pip install -r requirements.txt
```

### Python example

```python
import re
from pathlib import Path

PINNED = re.compile(r"^[A-Za-z0-9_.\-\[\]]+==\S+$")

def unpinned(requirements: Path) -> list[str]:
    lines = [line.strip() for line in requirements.read_text().splitlines()]
    return [line for line in lines if line and not line.startswith("#") and not PINNED.match(line)]
```

## Sources

- [pip documentation](https://pip.pypa.io/)
- [venv](https://docs.python.org/3/library/venv.html)

## Related rules

- [Make builds repeatable](https://agentwranglers.se/playbook/engineering/running-in-production/reproducible-builds) in Engineering

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/stack/languages-and-runtimes/pip-and-venv">Agent Wranglers software choices playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Use npm with a lock file for JavaScript packages](https://agentwranglers.se/playbook/stack/languages-and-runtimes/npm)
- Next: [Learn SQL and write it with parameters](https://agentwranglers.se/playbook/stack/languages-and-runtimes/sql)
- [Languages and runtimes](https://agentwranglers.se/playbook/stack/languages-and-runtimes)