Skip to content
Tutorials

Python Environments with uv: Projects, Lockfiles, Python Versions and Tools

AIDToolStack EditorialNovember 7, 20267 min read
pythonuvvirtualenvdependencieslockfiles
Share:Twitter

A Python repo's README says: install Python 3.12, create a virtualenv, pip install -r requirements.txt. Three people follow it and get three environments, because one has 3.13 on their PATH, one forgot to activate the venv, and the requirements file pins nothing below the top level. uv attacks all three problems with one binary: it installs interpreters, creates environments, resolves and locks dependencies, and runs tools. Its docs position it as a replacement for pip, pip-tools, pipx, poetry, pyenv, twine and virtualenv.

As of November 2026 the current release is uv 0.13.7, published on 3 November (PyPI). It moves fast, and two recent releases changed defaults you'll notice:

  • 0.12.0 (28 July 2026): uv init creates a packaged project by default, with a uv_build build backend, source under src/<name>/ and a [project.scripts] entry, per the 0.12 changelog. The older flat layout with main.py is now uv init --no-package.
  • 0.13.0 (9 October 2026): the default Python for downloads moved from 3.14 to 3.15, the cache format changed (so the first run after upgrading may re-download or rebuild packages), and --require-hashes in included constraints files is now enforced (changelog).

A disclosure before the commands: uv isn't installed on the machine I wrote this on, so I couldn't run these myself. Every command and every output shown here comes from uv's own docs and changelog, linked where used.

The model: three files and two commands

Diagram: pyproject.toml holds the version ranges you edit; uv lock turns it into uv.lock with exact pins that you commit; uv sync makes .venv match the lockfile; .python-version picks the interpreter for .venv. uv run checks the lock is current, syncs, then runs your command, and uv add and uv remove edit pyproject.toml and update the other two
Diagram: pyproject.toml holds the version ranges you edit; uv lock turns it into uv.lock with exact pins that you commit; uv sync makes .venv match the lockfile; .python-version picks the interpreter for .venv. uv run checks the lock is current, syncs, then runs your command, and uv add and uv remove edit pyproject.toml and update the other two

Once this picture clicks, the rest of uv is details:

  • pyproject.toml holds what you asked for: ranges like httpx>=0.27.2.
  • uv.lock holds what you got. The projects guide describes it as a cross-platform lockfile of exact resolved versions, in human-readable TOML, that "should be checked into version control" and "should not be edited manually."
  • .venv is what's installed, and you never need to touch it by hand.

uv lock goes from the first to the second, uv sync from the second to the third, and uv run does both checks before running your command.

Starting a project

uv init example
cd example
uv add httpx
uv add --dev pytest
uv run example        # the docs show: Hello from example!
uv run pytest

Per the init docs, that gives you .python-version, README.md, pyproject.toml and src/example/__init__.py, and uv add creates .venv and uv.lock on first use. The dependencies page shows what lands in pyproject.toml: runtime packages go in [project] dependencies with a lower bound at the version uv resolved, and --dev packages go into a PEP 735 dependency group:

[project]
name = "example"
version = "0.1.0"
dependencies = ["httpx>=0.27.2"]

[dependency-groups]
dev = ["pytest>=8.1.1,<9"]

[build-system]
requires = ["uv_build>=0.13.0,<0.14"]
build-backend = "uv_build"

(The version numbers above are the docs' examples, not recommendations; the uv_build bound is the one the 0.13 changelog suggests.) If you hand-edit this file, our TOML formatter parses it as TOML 1.0, reports the first error (such as a duplicated key or table) and aligns the keys. It checks syntax, not what the settings mean, so let uv have the final word.

Migrating an existing project is one command: uv add -r requirements.txt imports the lot.

lock, sync and run in practice

CommandWhat it does
uv lockResolve pyproject.toml into uv.lock
uv lock --upgrade-package httpxBump one package, keep everything else pinned
uv syncMake .venv match the lockfile exactly, removing anything extra
uv run <cmd>Check the lock is current, sync without removing extras, then run
uv run --locked <cmd>Fail if uv.lock is out of date instead of updating it
uv run --frozen <cmd>Use the lockfile as-is without checking it
uv sync --no-devSkip the dev group, which is otherwise synced by default

The sync docs cover the exact-versus-inexact detail: uv sync removes packages that aren't in the lock, uv run doesn't unless you pass --exact. In CI, --locked is the one you want, because a lockfile that doesn't match pyproject.toml should fail the build rather than quietly change.

The same page lists the export formats: uv export --format requirements.txt for tools that still want one, --format pylock.toml for the standard lock format from PEP 751 (final since March 2025), and --format cyclonedx1.5 for an SBOM. If that last one is new to you, Generating an SBOM explains what to do with it.

Python versions without pyenv

uv python install 3.14     # latest 3.14.x
uv python pin 3.14         # writes .python-version
uv python list --only-installed

From the Python versions docs: managed CPython builds come from Astral's python-build-standalone project, and downloads are automatic by default when a command needs a version you don't have. The default python-preference is managed, but an existing system Python still beats downloading a new one. Set python-downloads = "manual" if you'd rather uv never fetch interpreters on its own.

That 0.13 change to 3.15 as the default matters for anything with compiled dependencies. Python 3.15 was released on 9 October 2026 (python.org), and packages with compiled extensions need wheels built for each new Python version, which can take a while to appear. Our local LLMs post, for example, notes vLLM's install docs list Python 3.11 to 3.14. Pin explicitly in projects like that: uv python pin 3.14, or uv venv --python 3.14 for a plain environment.

Plain venvs and the pip interface

Not every repo needs to become a uv project. For an existing requirements.txt workflow, uv is a faster drop-in (environment docs):

uv venv                     # creates .venv
source .venv/bin/activate
uv pip install -r requirements.txt

One difference from pip: uv requires a virtual environment by default, and installing into the system Python needs an explicit --system. When you don't activate anything, uv looks for VIRTUAL_ENV, then CONDA_PREFIX, then a .venv in the current or nearest parent directory. That rules out the classic mistake of installing into the global interpreter by accident.

Tools: uvx and uv tool install

uvx is short for uv tool run, and it runs a command-line tool in a temporary, isolated environment (tools guide):

uvx ruff check                    # run without installing
uvx ruff@latest check             # force the newest version
uvx --from httpie http            # package and command names differ
uv tool install ruff              # keep it on your PATH
uv tool upgrade --all

The @ form only takes an exact version or latest; use --from 'ruff>0.2.0,<0.3.0' for ranges. The rule for uvx versus uv run: if the tool needs to import your project, as pytest and mypy do, use uv run so it sees your environment. Formatters and linters that only read files are fine with uvx.

You'll also see uvx as the launcher for Python MCP servers. The custom MCP server walkthrough installs the SDK with uv add "mcp[cli]" and shows servers published to PyPI being run with uvx.

Single-file scripts with inline metadata

For a one-off script, a whole project is overkill. PEP 723 (final, now maintained as the PyPA "Inline script metadata" spec) lets the script declare its own dependencies in a comment block, and uv reads it (scripts guide):

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = [
#   "httpx",
#   "rich",
# ]
# ///
import httpx
from rich import print

print(httpx.get("https://pypi.org/pypi/uv/json").json()["info"]["version"])

chmod +x it and run it directly, and uv sets up the environment the block describes. uv add --script fetch.py rich writes the block for you, and uv lock --script fetch.py creates fetch.py.lock beside it. For long-term reproducibility without a lockfile, the guide shows exclude-newer in a [tool.uv] section of the block, which ignores anything published after a given timestamp.

CI on GitHub Actions

uv's GitHub integration guide recommends pinning actions to commit SHAs and pinning the uv version. Its steps boil down to:

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
    with:
      enable-cache: true
  - run: uv python install
  - run: uv sync --locked --all-extras --dev
  - run: uv run pytest

The guide says that bare uv python install "will respect the Python version pinned in the project," so CI and laptops get the same interpreter. More on caching and matrix builds is in GitHub Actions CI/CD patterns.

Checklist for a uv-managed repo

  1. Commit pyproject.toml, uv.lock and .python-version. Don't commit .venv.
  2. Pin Python explicitly if any dependency has compiled extensions, at least until 3.15 wheels catch up.
  3. Put test and lint tools in the dev group; use uvx for one-off tools.
  4. Use uv sync --locked (or uv run --locked) in CI.
  5. Upgrade one package at a time with uv lock --upgrade-package, and review the uv.lock diff.
  6. Export pylock.toml or requirements.txt only when another installer needs it.
AE

Written by AIDToolStack Editorial

Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.

Sources

  1. docs.astral.sh/uv/
  2. pypi.org/project/uv/
  3. github.com/astral-sh/uv/blob/main/CHANGELOG.md
  4. github.com/astral-sh/uv/blob/main/changelogs/0.12.x.md
  5. docs.astral.sh/uv/guides/projects/
  6. docs.astral.sh/uv/concepts/projects/init/
  7. docs.astral.sh/uv/concepts/projects/dependencies/
  8. docs.astral.sh/uv/concepts/projects/sync/
  9. docs.astral.sh/uv/concepts/python-versions/
  10. docs.astral.sh/uv/guides/install-python/
  11. docs.astral.sh/uv/pip/environments/
  12. docs.astral.sh/uv/guides/tools/
  13. docs.astral.sh/uv/guides/scripts/
  14. docs.astral.sh/uv/guides/integration/github/
  15. peps.python.org/pep-0723/
  16. peps.python.org/pep-0751/
  17. www.python.org/downloads/

Related Posts

Explore on AIDToolStack

Discover tools and servers featured in our directory.

MCP Servers

Trigger.dev Jobs MCP ServerManage Trigger.dev background jobs from your AI coding assistant. Monitor job runs, trigger tasks manually, inspect execution logs, manage schedules, and debug failed runs. The server provides operational visibility into your background job infrastructure — see which tasks are running, queued, or failed, and take action. Your AI can help diagnose job failures from execution logs, retry failed tasks, and optimize concurrency configurations for better throughput.Tailscale Network MCP ServerManage your Tailscale mesh VPN network from your AI coding assistant. View connected devices, manage ACLs, configure exit nodes, check device status, and manage DNS settings. The server provides visibility into your Tailscale network — see which machines are online, troubleshoot connectivity issues, manage network access policies, and configure routes. Useful for developers managing distributed infrastructure where Tailscale provides secure networking between services.Portainer Docker MCP ServerManage Docker environments through Portainer's API from your AI coding assistant. Control containers, images, networks, and volumes across multiple Docker hosts and Kubernetes clusters. The server provides tools for container lifecycle management, image pulling and building, stack deployment, and resource monitoring. Portainer's multi-environment management makes this server particularly valuable for teams managing containers across development, staging, and production environments.

Reviews

Sign in to leave a review.

No reviews yet. Be the first!

Comments

Sign in to leave a comment.

No comments yet. Be the first!

Sponsor Our Newsletter

Reach thousands of developers who are actively evaluating AI tools, MCP servers, and dev infrastructure. Our weekly newsletter goes to engaged technical decision-makers.

Growing subscriber baseHigh open rates

All sponsored content is clearly labeled per our editorial policy.