uv Is Becoming the Default Python Toolchain. Here Is the Beginner Setup
A practical uv Python package manager guide covering installation, virtual environments, pyproject.toml, uv run, uv sync, lockfiles, scripts, and migration from pip.
In This Article
Why Python Developers Are Moving to uv
Python setup has always had a clutter problem. Beginners meet pip, venv, pyenv, pip-tools, pipx, Poetry, requirements.txt, pyproject.toml, lockfiles, and shell activation rules before they even run the project.
uv is popular because it combines several of those jobs into one fast command-line tool. The high-interest keywords around uv are simple: uv Python, uv package manager, uv venv, uv pip, uv run, uv sync, pyproject.toml, and Python lockfile.
The practical value is not only speed. uv gives teams a more repeatable workflow: create a project, declare dependencies, run commands through the managed environment, and keep a lockfile for reproducible installs.
Start With a Project, Not Random Global Installs
For a new app, use uv init, then run the generated Python file with uv run. A uv project is centered on pyproject.toml, which is now the main place modern Python tools read project metadata and dependencies.
When you run project commands, uv can create the .venv environment and uv.lock file when needed. That keeps the project environment near the project instead of scattering packages across your system Python.
If you are coming from pip, think of uv as a safer default path: project first, environment second, install third. Avoid installing into system Python unless you are in a container or CI setup where that is intentional.
Understand uv venv, uv pip, and uv run
uv venv creates a virtual environment. uv pip install can install packages into that environment. uv run runs a command inside the project environment and can make sure dependencies are present first.
That distinction helps beginners. Use uv run python main.py instead of wondering whether the right environment is activated. Use uv add requests when the dependency belongs to the project. Use uv pip install when you are intentionally working with pip-style flows or existing requirements files.
The most common mistake is mixing tools without a rule. Pick one workflow per project and write the commands in the README so future you does not guess.
Lockfiles Are the Main Team Benefit
A lockfile records the exact resolved package versions. uv creates and updates uv.lock so the team, CI, and production build can install the same dependency graph instead of whatever happens to be latest that day.
Use uv sync when you want the environment to match the lockfile. Use uv lock --check or locked CI workflows when you want to catch dependency changes that were not committed.
Do not ignore lockfile diffs. Review them like code when dependencies change, especially for web apps, data tools, machine learning notebooks, and anything deployed to users.
Scripts and One-Off Tools Get Easier Too
uv is not only for full apps. It also helps with single-file scripts that need dependencies. That is useful for data cleanup, report generation, API checks, automation, and small internal tools.
For a script you share with coworkers, keep the dependency metadata with the script or place it inside a small project. The goal is that another person can run the same command without manually reading a setup paragraph.
This is where uv saves real time: fewer hidden global installs, fewer "works on my machine" packages, and fewer mystery virtual environments.
A Safe Migration Checklist
For an existing Python project, do not rewrite everything at once. First, commit the current requirements files and passing tests. Then create or update pyproject.toml, run uv sync, run tests, and compare the resulting lockfile.
If the project has deployment scripts, notebooks, Dockerfiles, GitHub Actions, or Makefile targets, migrate those commands deliberately. Keep old commands documented until the new flow is proven.
The best uv setup is boring: uv run for commands, uv add for dependencies, uv sync for environments, uv.lock committed, and clear notes for contributors.