Python Environment Setup: venv vs uv (A Practical Guide for Modern Developers)

Whether you're building an API, ETL pipeline, data analysis project, automation script, applications, or desktop tool, setting up your development environment is the first step before writing code.

The two common approaches explored in this article:

1. The traditional venv + pip workflow
2. The modern uv workflow

Why Environment Setup Matters

A properly configured development environment helps you:

• Isolate project dependencies
• Prevent version conflicts
• Reproduce projects across different machines
• Share dependencies with teammates
• Maintain cleaner repositories
• Follow industry best practices

Without an isolated environment, a package installed for one project can accidentally break another project.

Understanding Virtual Environments

A virtual environment is an isolated Python workspace containing its own:

• Python interpreter
• Installed packages
• Project dependencies

Instead of installing libraries globally on your machine, they are installed only for the project that needs them.

For example:

Project A → pandas 2.2
Project B → pandas 1.5

Because each project has its own environment, they can coexist without conflicts.

Approach 1: Using venv (The Traditional Workflow)

For years, venv has been the standard way to create isolated Python environments.

The module ships with Python, making it available on virtually every installation.

i. Create a Project Directory

mkdir my-project
cd my-project

ii. Create a Virtual Environment

python -m venv venv

This creates a folder called venv that contains the isolated environment.

iii. Activate the Environment

Git Bash

source venv/Scripts/activate

PowerShell

.\venv\Scripts\Activate.ps1

Command Prompt

venv\Scripts\activate.bat

After activation, your terminal prompt should look similar to:

(venv)

iv. Upgrade pip

It's good practice to update the package manager before installing dependencies.

python -m pip install --upgrade pip

v. Install Packages

pip install pandas requests

vi. Save Dependencies

Create a requirements file:

pip freeze > requirements.txt

Example:

pandas==2.3.0
requests==2.32.0

vii. Recreate the Environment

If another developer clones the repository:

pip install -r requirements.txt

The same dependencies will be installed.

Typical venv Project Structure

my-project/
│
├── venv/
├── data/
├── output/
├── src/
│   └── main.py
│
├── requirements.txt
├── README.md
└── .gitignore

Limitations of venv

As projects grow, developers may encounter:

• Slower package installation
• Manual dependency tracking
• Multiple tools for environment management
• Extra setup steps

This is where modern tools like uv come in.

---

Approach 2: Using uv (The Modern Workflow)

uv is a fast Python package and project manager written in Rust.

It combines several common Python development tasks into a single tool, providing a cleaner developer experience.

Many developers now use uv for new projects because it simplifies dependency management and significantly speeds up package installation.

i. Install uv

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify Installation

uv --version

ii. Create a New Project

Initialize a project:

uv init my-project
cd my-project

This automatically generates a modern Python project structure.

iii. Create a Virtual Environment

uv venv

The environment is typically created in:

.venv/

iv. Activate the Environment

Git Bash

source .venv/Scripts/activate

PowerShell

.\.venv\Scripts\Activate.ps1

v. Install Dependencies

uv add pandas requests

Unlike the traditional workflow, dependencies are automatically recorded for you.

vi. Run Python Programs

uv run main.py

You can execute scripts directly inside the project's environment.

vii. Sync Dependencies

When moving between machines or cloning a project:

uv sync

This recreates the project's environment based on its configuration files.

Typical uv Project Structure

my-project/
│
├── .venv/
├── src/
│   └── main.py
│
├── pyproject.toml
├── uv.lock
├── README.md
└── .gitignore

---

Important Files Explained

requirements.txt

Used primarily in traditional Python projects.

Example:

pandas==2.3.0
requests==2.32.0

Dependencies are installed with:

pip install -r requirements.txt

pyproject.toml

The modern standard for Python project configuration.

Example:

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "pandas",
    "requests"
]

uv.lock

Locks dependency versions to ensure consistent environments across machines.

This helps eliminate the classic "works on my machine" problem.

.gitignore

Whether you use venv or uv, avoid committing environment files to GitHub.

# Virtual environments
venv/
.venv/

# Python cache
__pycache__/
*.pyc

# IDE settings
.vscode/

* Environment variables
.env

# Log**logs/

# OS files
.D*_Store
Thumbs.db

venv vs uv

Feature	venv	uv
Package Installation Speed	Standard	Very Fast
Dependency Management	Manual	Automatic
Workflow	Traditional	Modern
Project Initialization	Manual	Built-in

Final Thoughts

A properly managed environment leads to:

• Cleaner projects
• Reproducible builds
• Easier collaboration
• Fewer dependency issues
• Better development habits

The fundamentals remain the same. The tools are simply evolving to make the process faster, cleaner, and more reliable.