How to Use uv Python Package Manager (Complete 2026)

uv is the Python package manager that changed how I work in 2025-2026. Built by Astral (creators of Ruff), uv is 10-100x faster than pip, poetry, or pipenv, and it manages everything, projects, virtual environments, Python versions, and dependencies, from a single tool. This complete 2026 tutorial covers install, setup, and daily use.

Why uv is a big deal

• Blazing fast: written in Rust, resolves dependencies in seconds.
• All-in-one: replaces pip + poetry + pipenv + pyenv + virtualenv.
• Manages Python itself: installs and switches Python versions.
• Cross-platform: Windows, Mac, Linux.
• Free and open source.
• Compatible: works with existing pip requirements.txt, poetry pyproject.toml.

Install uv

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

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

# Or via pip (slower to install but works)
pip install uv

# Or via Homebrew (Mac)
brew install uv

# Verify install
uv --version

Create a new project

uv init my-project
cd my-project

# uv creates:
# - pyproject.toml (project metadata)
# - .python-version (Python version pin)
# - README.md
# - src/my_project/ folder
# - .gitignore

Add dependencies

# Add a package
uv add requests

# Add multiple
uv add fastapi uvicorn pydantic

# Add with version constraint
uv add "django>=5.0"

# Add dev dependency
uv add --dev pytest black ruff

# Add optional dependency group
uv add --optional docs sphinx

Remove dependencies

uv remove requests
uv remove --dev pytest

Run Python code

# Run a script (auto-activates virtual env)
uv run python main.py

# Run a specific command in the project env
uv run pytest

# Run a one-off script with inline deps (script mode)
uv run --with pandas --with requests script.py

Virtual environments

# uv auto-creates .venv in project root
# No need to activate manually, uv run handles it

# But you CAN activate if you want:
source .venv/bin/activate      # macOS/Linux
.venv\Scripts\activate         # Windows

# Explicit venv creation
uv venv                         # in current project
uv venv --python 3.12 my-env    # specific Python version + name

Manage Python versions

# List available Python versions
uv python list

# Install specific Python
uv python install 3.12

# Pin project to specific Python
uv python pin 3.12

# Use different Python for a project
uv init --python 3.11 my-project

Install from requirements.txt (migration)

# From requirements.txt
uv pip install -r requirements.txt

# From poetry pyproject.toml (works out of the box)
uv sync

# Freeze current environment
uv pip freeze > requirements.txt

Lock file (uv.lock)

uv generates uv.lock automatically, commit it to git. This ensures reproducible installs across all developers:

# uv.lock is created on first uv add
# Contains exact resolved versions of all deps + transitive deps

# Sync to lock file
uv sync

# Update all deps to latest allowed by pyproject.toml
uv sync --upgrade

# Update single package
uv sync --upgrade-package fastapi

uv daily workflow

morning:
git pull
uv sync                    # get latest deps

work:
uv add some-package        # add new dep
uv run python main.py      # run code
uv run pytest              # test

commit:
git add pyproject.toml uv.lock
git commit -m "add some-package"

That's it. No activate/deactivate. No poetry install. No pip freeze.

Common uv commands cheatsheet

uv init [name]              # new project
uv add [pkg]                # add package
uv remove [pkg]             # remove package
uv sync                     # install all deps from lock
uv run [cmd]                # run command in project env
uv pip [pip-cmd]            # pip compatibility layer
uv python install [ver]     # install Python version
uv python pin [ver]         # pin Python for project
uv venv                     # create virtual env
uv tree                     # show dependency tree
uv lock                     # regenerate lock file

When NOT to use uv

• Legacy projects with heavy pip customization.
• Corporate environments with locked-down tooling.
• Very old Python versions (uv works with 3.8+).
• If your team standardizes on Poetry and won’t change.

Common how mistakes to avoid

• Skipping the “why” before adopting a new tool. Modern Python tools (uv, Ruff, Polars) are fast and clean. But adopting them without understanding what problem they solve wastes time. Read the tool’s motivation section first.
• Migrating everything at once. Legacy code bases have too many surprises. Migrate one module at a time and test after each step.
• Ignoring backwards compatibility. New Python tools sometimes break with older Python versions. Verify your target Python version supports the tool before committing.
• Trusting benchmarks blindly. “10x faster than X” often means “10x faster for one specific workload”. Test with YOUR data before assuming the benchmark generalizes.
• Not reading the CHANGELOG. Every dependency upgrade may break something. Skimming the changelog for breaking changes takes 2 minutes and saves hours.

Adoption path for how

1. Read official docs cover-to-cover for the core concepts. Yes, cover-to-cover.
2. Complete the official tutorial project. Follow along exactly, no shortcuts.
3. Adapt one small piece of your existing project to the new tool. Ship it.
4. If it survives 2 weeks in production, expand adoption.
5. If it caused issues, rollback and reassess whether the tool fits your use case.

When to use vs when to stick with what you know

Modern Python tools offer real improvements over their predecessors, but “better” is not the same as “necessary for you.” Consider adopting when:

• Your current tool is slow enough to block productivity (uv/Ruff speedups matter here).
• You are starting a new project with no legacy constraints.
• Your team has bandwidth to learn and support the new tool.
• The tool has been stable and community-adopted for 12+ months.

Stick with your existing tools when: production stability is critical and you have working infrastructure; your team is small and cannot afford learning curves; the tool is early-stage and API may change.

Ecosystem integration considerations

Every new Python tool interacts with the broader ecosystem. Before committing, check:

• Does your CI/CD pipeline support it? Most tools have GitHub Actions and GitLab CI templates.
• Does your IDE support it? VS Code and PyCharm have first-class support for most modern tools. Older editors may lag.
• Do dependency scanners (Snyk, Dependabot) recognize it? Ensures security updates get flagged.
• Is there production monitoring integration? Datadog, Sentry, New Relic support matters for production.

For teams shipping production Python code, the ecosystem answer is often more important than the tool answer. A slightly-worse tool that plays well with your stack beats a slightly-better tool that fights it.

Best practices summary

• Read the docs before Stack Overflow. Official docs are cleaner and more accurate than forum answers.
• Pin versions in production. Locked dependencies prevent surprise breakage. Update deliberately, not accidentally.
• Test after every dependency upgrade. Run the full test suite. Catch regressions before deployment.
• Contribute back. Report bugs, submit fixes, write tutorials. The tools improve when users engage.
• Reassess yearly. The Python ecosystem moves fast. What was best last year may be second-best today.

Quick step-by-step summary (click to expand)

1. Install uv. Run curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux, or use pip install uv as a fallback.
2. Create a new project. Run uv init myproject to scaffold a pyproject.toml, README, and .python-version file.
3. Add dependencies. Run uv add requests pandas to install packages and pin them in pyproject.toml automatically.
4. Run scripts in a synced env. Run uv run python script.py to execute in the project virtual environment. uv handles the venv for you.
5. Lock and sync. Run uv lock to generate uv.lock, then uv sync on any machine to install the exact same dependency versions.