How To Use uv: The Fast Python Package Manager

Beginner

Python package management is one of the most critical parts of Python development. Whether you’re installing libraries, managing dependencies, or creating reproducible environments, you need a reliable package manager. For years, pip has been the de facto standard, but it’s slow, fragmented, and sometimes frustrating to use. Enter uv—a blazing-fast Python package manager written in Rust that replaces pip, virtualenv, and poetry with a single, unified tool.

In this comprehensive guide, we’ll explore uv from the ground up. You’ll learn how to install it, use it to manage projects and dependencies, understand how it differs from traditional tools, and discover why developers are rapidly adopting it. By the end, you’ll understand why uv is being called “the next-generation Python package manager.”

What is uv?

uv is a modern Python package manager that’s designed to be ridiculously fast. Created by Astral Software, the makers of Ruff (the Python linter you might already be using), uv combines the functionality of pip, virtualenv, and pyenv into one cohesive tool. But that’s not the main selling point—the main point is speed.

Here’s what uv is NOT: it’s not a replacement for pip that works the same but faster. It’s a rethinking of what a Python package manager should be. It’s designed from scratch using Rust, with modern parallelization, caching, and optimization.

Why Choose uv?

• 10-100x faster: Installation is dramatically faster due to Rust performance and parallel downloads
• Single tool: Replaces pip, virtualenv, and pyenv—no more context switching
• Dependency resolution: Lightning-fast conflict detection and resolution
• Cross-platform: Works on Windows, macOS, and Linux without modification
• Built for modern Python: Designed with Python 3.8+ in mind from the start
• Zero configuration needed: Works out of the box with sensible defaults

Installing uv

Installing uv is incredibly simple. On macOS or Linux, just run:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, use:

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

That’s it. uv is now installed and ready to use.

Basic uv Commands

Creating a New Project

To create a new Python project with uv, simply run:

uv init my_project

This creates a new directory with a basic project structure:

my_project/
├── .python-version      # Python version specification
├── pyproject.toml       # Project configuration
└── src/
    └── my_project/
        └── __init__.py

Adding Dependencies

To add a package to your project:

uv add requests

This automatically:

• Resolves the dependency
• Installs it
• Updates your pyproject.toml
• Creates a uv.lock file for reproducibility

Installing from pyproject.toml

To install all dependencies from your pyproject.toml:

uv sync

This ensures exact version matching for reproducibility.

Running Python Scripts

With uv, you don’t need to manually activate virtual environments:

uv run python script.py

uv automatically creates and uses the appropriate environment.

Advanced Usage

Python Version Management

uv can automatically manage Python versions. To use a specific Python version in your project:

uv init --python 3.11

To list available Python versions:

uv python list

Working with Virtual Environments

Create an environment explicitly:

uv venv

Activate it like you normally would:

source .venv/bin/activate  # On Windows: .venvScriptsactivate

Pre-Release and Development Versions

To include pre-release versions in dependency resolution:

uv add --pre package_name

Comparing with Pip and Poetry

Here’s how uv stacks up against traditional tools:

Feature	uv	pip	poetry
Installation Speed	10-100x faster	Baseline	2-3x faster than pip
Single Tool	Yes	No (+ virtualenv + pip)	Yes
Lock File	Yes (uv.lock)	No (requires pip-tools)	Yes (poetry.lock)
Ease of Use	Very Easy	Moderate	Very Easy
Performance	Excellent	Good	Good
Python Version Management	Built-in	Requires pyenv	Requires pyenv

Real-World Example: Setting Up a Data Science Project

Here’s how you’d set up a complete data science project with uv:

# Create the project
uv init data_science_project

# Enter the directory
cd data_science_project

# Add scientific computing dependencies
uv add numpy pandas scikit-learn jupyter matplotlib

# Add development dependencies (optional)
uv add --dev pytest pytest-cov black

# Run Jupyter notebooks
uv run jupyter notebook

# Run tests
uv run pytest

Notice how simple that is? No manual environment activation, no separate commands for different tools. Everything flows naturally.

Frequently Asked Questions

Is uv production-ready?

Absolutely. While it’s relatively new, it’s being used in production by many organizations. The Astral team is committed to stability, and it continues to improve with every release.

Will uv replace pip?

Eventually, yes. Many Python developers are switching to uv. However, pip will likely remain the standard for a while. The Python ecosystem moves slowly, and that’s a good thing.

Can I use uv alongside pip?

You shouldn’t mix package managers in the same environment, but you can use uv for some projects and pip for others.

What about compatibility?

uv is compatible with PyPI and all standard Python packages. There’s no special “uv-only” ecosystem—it works with everything pip does.

Conclusion

uv represents the future of Python package management. It’s fast, simple, and incredibly well-designed. Whether you’re building a small script, a data science project, or a large production application, uv makes package management feel effortless. If you haven’t tried it yet, I highly recommend giving it a shot. Your development workflow will thank you.

Key Takeaways:

• uv is a faster, more unified replacement for pip, virtualenv, and pyenv
• Installation is a single command
• Project setup and dependency management are incredibly straightforward
• It’s production-ready and actively maintained
• Making the switch is risk-free—it’s fully compatible with the existing Python ecosystem

Installing uv

uv is a single static binary written in Rust — no Python interpreter dependency, no package install dance. The installer pulls the right binary for your platform:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Or via pip if you prefer
pip install uv

# Verify
uv --version

The standalone installer puts uv in ~/.cargo/bin/uv and adds it to PATH. That location is shell-aware — restart your terminal or run source ~/.bashrc after install.

Replacing pip and venv

uv handles both package install AND virtual environments — replacing pip + venv with one tool. The most common workflows:

# Create a virtualenv
uv venv                          # creates .venv in current dir
uv venv my-env                   # custom name
uv venv --python 3.11            # specific Python version

# Activate (same as venv)
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows

# Install packages
uv pip install requests pandas
uv pip install -r requirements.txt
uv pip install -e .              # editable install

# Show what's installed
uv pip list
uv pip freeze > requirements.txt

The uv pip ... command is intentionally drop-in compatible — every pip invocation you know works the same. The speed difference is what shocks you: a 60-second pip install -r requirements.txt typically becomes 2-3 seconds.

Project Workflow with uv init

uv also has a project mode (similar to Poetry, Hatch, or PDM) that manages your pyproject.toml, lockfile, and venv in one place:

# Start a new project
uv init my-app
cd my-app

# Add dependencies (updates pyproject.toml and lockfile)
uv add requests pandas
uv add --dev pytest mypy

# Run any command in the project's venv
uv run python my_script.py
uv run pytest

# Reproduce the lockfile environment exactly
uv sync

The uv.lock file is the cross-platform lockfile — committed to git, identical resolutions on macOS / Linux / Windows. uv sync rebuilds the venv exactly from the lock, perfect for CI.

Managing Python Versions

uv can also install Python itself — no more pyenv, no more system Python pollution:

# Install a specific Python version
uv python install 3.12
uv python install 3.13

# List installed Python versions
uv python list

# Pin a project to a specific Python
echo "3.12" > .python-version
uv venv                          # uses 3.12

# Or pass version explicitly
uv venv --python 3.13

This obsoletes pyenv for most use cases. uv downloads Python from the python-build-standalone project — full, properly-built CPython binaries.

Migrating from pip / Poetry / pipenv

If you have an existing project, migration is mostly painless:

• From pip + requirements.txt: Just start using uv pip install -r requirements.txt. No file changes needed.
• From Poetry: uv init in the project, then uv add each dependency from pyproject.toml. Or use the experimental uv import command.
• From pipenv: uv pip install -r <(pipenv requirements) as a one-liner. Then drop pipenv entirely.

Common Pitfalls

• Mixing uv and pip in the same venv. Both work, but you’ll get inconsistent results if you bounce between them. Pick one tool per project.
• Forgetting to activate the venv. uv pip install installs into the ACTIVE venv. If none is active, it installs to system Python — usually not what you want. Always activate first or use uv run.
• Lockfile drift. If you edit pyproject.toml manually without running uv sync, the lockfile gets out of sync with your stated dependencies. Always use uv add / uv remove.
• Treating uv as a complete Poetry replacement. uv’s project mode is newer than Poetry’s. Some plugin ecosystems (publishing tools, build backends) are more mature on Poetry. Check your specific use case before committing.
• Caching across versions. uv’s cache (~/.cache/uv) is shared across projects. If something behaves weirdly, uv cache clean is the nuclear option.

FAQ

Q: Is uv stable enough for production?
A: Yes — Astral (the company behind uv and ruff) ships it at production scale. The pip-compatible commands are battle-tested. The newer “uv init / uv add / uv sync” project mode is solid but still evolving.

Q: How is uv faster?
A: Rust implementation, parallel downloads, parallel resolves, fast metadata caching, and aggressive use of HTTP/2. Most installations are bottlenecked on pypi metadata fetching — uv parallelizes that work to saturate the network.

Q: Do I lose anything by switching from pip?
A: Almost nothing. Edge cases around custom indexes and certain proxy configs may need adjustment. The uv pip subcommand is intentionally a near-perfect drop-in.

Q: uv or Poetry?
A: uv if you value speed and a single binary. Poetry if you have an established workflow, plugins, or your team is on Poetry already. They solve overlapping problems with different opinions.

Q: Does uv work on Windows?
A: Yes, with the official installer. The CLI is identical to Linux / macOS. Some plugin and binary-wheel edge cases are slightly different but the core workflow is the same.

Wrapping Up

uv is the rare new tool that you can adopt incrementally — start by aliasing pip to uv pip and feel the speed difference today. As you get comfortable, graduate to uv venv and uv python install to replace virtualenv + pyenv. The project workflow (uv init / add / sync) is the long-term destination, but you don’t have to commit on day one. For a tool that’s still under 18 months old, uv is remarkably stable and unusually fast.

Related Python Tutorials

Continue learning with these related guides:

• Python Virtual Environments Explained: venv, conda, and uv
• How To Manage Environment Variables with dotenv
• How To Use Python subprocess Safely