uv is one of those tools where there is pretty much no reason not to use it.

uv is a plug-n-play, drop in replacement for pip, pipx, pip-tools, venv, pyenv, virtualenv. uv is written in Rust so it is fast, like insanely fast. For someone that has used conda for a significant part of their Python journey, which has the speed of a wheelchair bound sloth with arthritis, it was like I was an American going out of the country for the first time. It was a godsend.

The company behind uv, Astral, is an actual legitimate VC backed startup, which means it commands resources necessary for ongoing development. Not all VC companies are evil that the tooling Astral creates like ruff and uv are some of the best in the Python ecosystem. I'm hoping they don't pull a redis or Terraform or something like that.

Installation

You can install uv both with their standalone installers or with any package manager of your choice. I've listed the most common options here:

macOS and Linux

Open your terminal and paste this:

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

Windows

Open powershell and run this:

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

Alternative: Use pip

If you're not into pipe-to-shell installers (fair), you can use pip:

pip install uv

For the full list of installation options you should go to the official installation documentation here

Functionality

Before you do anything you should add the shell autocompletion:

eval "$(uv generate-shell-completion bash)"

You can then add this to either your ~/.bashrc or ~/.zshrc profiles so that it auto-loads in the future.

Starting Fresh: uv init

Creating a new project is dead simple:

uv init my-project
cd my-project

‍
This scaffolds out a basic Python project with a `pyproject.toml` file. It's clean, minimal, and ready to go. You'll get a basic structure that looks like this:

my-project/
├── pyproject.toml
├── README.md
└── hello.py

Running Code: uv run

Here's where things get interesting. Forget about activating virtual environments manually. Just use:

uv run python hello.py

uv automatically creates and manages a virtual environment for you (in .venv), installs your dependencies, and runs your script. No activation needed. It just works.

You can also run modules directly:

uv run -m pytest

Managing Dependencies: uv add, uv remove

Adding packages is painfully simple:

uv add requests
uv add pytest --dev

This updates your pyproject.toml and installs the package. The --dev flag marks it as a development dependency.

Need to remove something?

uv remove requests

Done. No fuss.

Locking Dependencies: uv lock

This is where uv shines. It creates a uv.lock file that pins exact versions of all your dependencies and their transitive dependencies:

uv lock

This lock file is cross-platform and ensures everyone on your team gets identical environments. It's like poetry.lock or Cargo.lock but faster.

Syncing Environments: uv sync

Got a lock file from a teammate? Sync your environment to match it exactly:

uv sync

This installs everything from the lock file. Perfect for CI/CD or onboarding new developers.

Inspecting Dependencies: uv tree

Ever wonder what's actually installed and why?

uv tree

This shows you a dependency tree of your project. You'll see what depends on what, making it easy to understand your dependency graph and spot issues.

Workspaces and Monorepos: uv init

Here's where uv gets really powerful. You can manage multiple related packages in a single repository:

uv init my-monorepo --workspace
cd my-monorepo
uv init packages/core
uv init packages/cli

Your root pyproject.toml defines the workspace:

[tool.uv.workspace]
members = ["packages/*"]

Now you can:

• Share dependencies across packages
• Develop packages together with proper isolation
• Run commands across the entire workspace

This is game-changing for larger projects or internal tooling.

One-Off Tools: uv tool run, uvx

Need to run a tool without installing it globally?

uv tool run ruff check .

Or use the shorthand uvx:

uvx ruff check .

This downloads and runs the tool in an isolated environment. Think of it like npx for Python. No pollution of your global Python environment.

Installing Tools Globally: uv tool install

For tools you use regularly, install them globally:

uv tool install ruff
uv tool install black

These live in isolation from your projects but are available system-wide. Update them with:

uv tool update ruff

Or update everything at once:

uv tool update --all

Want shell completions for your tools? Run:

uv tool update-shell

This refreshes shell completions for all installed tools.

Publishing Packages: uv publish

Ready to share your package with the world?

uv publish

This builds and uploads your package to PyPI. You'll need credentials configured, but the command handles the rest. Clean and simple.

The New Build Backend: uv_build

uv now has its own build backend. In your pyproject.toml:

[build-system]
requires = ["uv-build>=0.1.0"]
build-backend = "uv_build"

This means:

• Faster builds
• Better reproducibility
• Native integration with uv's workflow

It's still early, but it's a sign of where Python packaging is heading.

‍

‍

‍

‍

‍

‍