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

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.