Igor's Techno Club

UV Venv – Fast Python Environment Setup

If you have been working with Python for any length of time, you know that virtual environments are essential for managing dependencies and keeping projects isolated. For years, developers have relied on python -m venv or tools like virtualenv to create these environments.

Now, there’s a faster, smarter way — uv, a modern Python package and environment manager from the creators of ruff. In this guide, we’ll cover two essential commands:

By the end, you’ll know how to create high-performance virtual environments, install your dependencies quickly, and avoid common pitfalls.

What is uv?

uv is a fast Python package and environment manager built in Rust. It combines the best features of multiple tools:

Key Benefits of uv

  1. Speed — Rust-powered and much faster than Python’s built-in tools.
  2. Built-in environment management — Create and manage venvs without extra commands.
  3. Cross-platform consistency — Works the same way on Windows, macOS, and Linux.
  4. Simplified dependency management — No need to juggle multiple tools.

Understanding uv venv -p

The command:

uv venv -p python3.11

means:

Without -p, uv uses the system’s default Python. With -p, you can target any installed version.

Example:

uv venv -p /usr/local/bin/python3.12

This will:

  1. Create a .venv directory in your current folder.
  2. Use Python 3.12 as the interpreter.
  3. Prepare the environment for package installations via uv pip.

Why Use -p?

In real-world projects, you often need to match a specific Python version — especially if production servers use an older version. If you use python -m venv without specifying, you might end up with a mismatch.

uv venv -p ensures your virtual environment uses exactly the version you want.

Creating a Virtual Environment with uv venv -p

Here’s the full process:

# 1. Navigate to your project folder
cd my_project

# 2. Create the environment with a specific Python version
uv venv -p python3.10

# 3. Activate the environment
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

Once activated, your shell prompt changes:

(.venv) user@machine:~/my_project$

Now you can install packages using uv pip install.

Installing Packages with uv pip install

uv pip works just like pip install but faster.

Example:

uv pip install requests

This installs the requests library into your .venv.

What Does uv pip install cluster main Do?

The command:

uv pip install cluster main

installs two packages into your current environment:

These can be:

Editable example:

uv pip install -e ./cluster ./main

This is great for monorepo projects where you have multiple internal packages.

Why Combine uv venv -p with uv pip install?

A typical workflow for a new Python project might be:

# Create an environment with a specific version
uv venv -p python3.11

# Activate it
source .venv/bin/activate

# Install dependencies
uv pip install cluster main

This ensures:

Advantages Over Traditional Pip + Venv

Feature python -m venv + pip uv
Speed Slow Very fast
Version selection No Yes (-p)
Package caching Limited Built-in
Cross-platform Mostly consistent Fully consistent
Dependency resolution Basic Optimized

Common Mistakes and How to Avoid Them

  1. Forgetting -p

    • Your environment may have the wrong Python version.

    • Check with:

      python --version

  2. Not activating the venv before install

    • Packages might install globally instead of in your project.

  3. Mixing pip and uv pip

    • This can cause caching issues. Stick to one installer.

Example: Setting Up a Data Project

Imagine you have two packages:

You could set it up like this:

# Create environment with Python 3.11
uv venv -p python3.11

# Activate it
source .venv/bin/activate

# Install both packages
uv pip install -e ./cluster ./main

Run your app:

python -m main