Python Virtual Environment Tutorial: venv, pip and uv

You install a package for one project and suddenly another project stops working. That is the classic dependency conflict, and it is why every developer needs a Python virtual environment.

A virtual environment gives each project its own isolated set of packages, so versions never collide. It takes about 30 seconds to set up and saves hours of debugging. In this tutorial you will create and activate one with venv, install packages with pip, save dependencies, try uv and fix common errors.

What is a Python virtual environment?

Without one, pip install puts packages in your global Python. Project A may need requests 2.28 while project B needs a newer version, and only one can win. A virtual environment is a folder with its own interpreter link and its own site-packages, so each project keeps the versions it needs.

Test automation projects pin versions of Selenium, Playwright or pytest so results are repeatable on every laptop and CI server. A virtual environment plus a requirements file is the foundation of that. New to the language? Start with our Python tutorial for beginners.

Create a Python virtual environment with venv

Step 1: check your Python version

python --version

On some systems the command is python3. The venv module ships with modern Python, so no extra install is needed. See the official venv documentation.

Step 2: create the environment

cd my-project
python -m venv .venv

This creates a .venv folder in your project. The name is a convention that many tools and editors detect automatically.

Step 3: activate it

When active, your prompt shows (.venv). Type deactivate to leave. If PowerShell blocks the script, allow local scripts for your user with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Install packages in your Python virtual environment with pip

pip install requests
pip list
pip install --upgrade requests

Check you are using the environment’s pip with pip --version; the path should point inside .venv. The pip user guide covers more options.

Save and restore dependencies

pip freeze > requirements.txt
# later, on another machine
python -m venv .venv
pip install -r requirements.txt

Commit requirements.txt so teammates and CI can rebuild the same environment. Not sure about commits? Read our Git tutorial for beginners. Add .venv/ to your .gitignore, because environments are large, machine specific and easy to recreate.

Try uv: a faster alternative

uv is a fast Python package and project manager written in Rust. It creates environments and installs packages much faster than plain pip and works with the same requirements.txt files.

uv venv
uv pip install requests
uv pip freeze > requirements.txt

Using a Python virtual environment in real projects

• VS Code: press Ctrl+Shift+P, choose “Python: Select Interpreter” and pick the .venv interpreter.
• CI pipelines: create a fresh environment, install from the requirements file and run tests, as in our GitHub Actions CI/CD guide.
• Containers: the same idea applies in images; see our Docker tutorial for beginners.
• API and test scripts: a small requests project in its own environment pairs well with API testing with Postman.

Common errors and fixes

Best practices: one environment per project, name it .venv in the project root, pin dependencies, ignore the folder in Git, recreate rather than repair, and document setup steps in the README.

Final thoughts

A Python virtual environment is the simplest habit that makes projects reproducible. Create one with python -m venv .venv, activate it, install what you need and freeze your dependencies. Once that feels natural, experiment with uv for speed, then put your environment to work on a small automation script or test project.

Frequently asked questions

Keep learning