Python package managers allow you to install and manage dependencies like Flask, Requests, and Matplotlib directly from your terminal. In this article, we will explore how to use uv, a modern and high-speed Python package manager that simplifies environment and dependency management for your projects.
1. What is uv?
uv is a modern, high-performance Python package manager built in Rust that serves as a drop-in replacement for pip, pip-tools, and virtualenv. It dramatically speeds up dependency installation using global caching, parallel execution, and optimized metadata fetching, while also reducing disk usage. By combining package management, virtual environments, and dependency locking into a single standalone tool, uv simplifies Python workflows and provides consistent, reliable environments across macOS, Linux, and Windows.
2. Installing uv
uv can be installed on macOS, Linux, or Windows. Here are the main options:
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"
Homebrew users
brew install uv
After installation, confirm the version:
uv --version
3. Creating and Initializing Projects
uv makes it easy to start new Python projects with all dependencies managed automatically.
Initialize a project
uv init my-project
This command scaffolds a new project directory and generates the essential project files, including:
pyproject.tomlfor project metadata and dependencies.python-versionto pin the Python interpreter version.gitignoreand a basicREADME.md
At this stage, uv prepares the project for dependency management but does not install any packages yet.
Adding Initial Project Dependencies
Once the project is initialized, we can add dependencies using:
uv add requests
When a dependency is added, uv automatically updates the pyproject.toml file, resolves all required transitive dependencies, installs the finalized packages into the project’s isolated virtual environment, and creates or refreshes the uv.lock file to capture exact versions, ensuring a consistent and reproducible dependency set from the outset.
Removing Dependencies
If a dependency is no longer needed, it can be removed with:
uv remove requests
This command removes the dependency from pyproject.toml, uninstalls it from the virtual environment, and updates the lockfile accordingly.
Run scripts in the project
After installing the required dependencies, you can begin developing and running your Python scripts as normal. uv offers multiple options for executing Python code, including running a script directly using the uv run command.
uv run main.py
The first run automatically creates a virtual environment (.venv) and generates a uv.lock file to lock project dependencies.
4. Managing Python Versions
uv makes it simple to manage multiple Python versions across projects, helping us avoid conflicts and ensuring that each project runs with the correct interpreter. To install a specific Python version, we can run:
uv python install 3.12
This command downloads and sets up the requested Python version, making it available to uv-managed projects. uv handles the installation in a way that keeps it isolated from system Python installations, avoiding conflicts with other Python versions on your machine.
To list all Python versions installed via uv, we can use:
uv python list
This displays all versions currently available through uv, making it easy to switch or select the appropriate Python version for any project.
Pinning a Python Version to a Project
Sometimes we want to ensure that a project always uses a specific Python version, regardless of other versions installed on your system. uv allows us to pin a Python version to a project, which locks the interpreter for that project’s virtual environment.
uv python pin 3.12
Running this command updates the project configuration to use Python 3.12 as the default interpreter. uv will automatically recreate or adjust the virtual environment if needed, installing all dependencies under the pinned version.
5. Understanding uv Tools and Their Usage
Many Python packages include command-line utilities that allow developers to perform tasks like code formatting, linting, testing, and type checking directly from the terminal. uv offers convenient ways to run these tools directly without permanently installing them in the project’s virtual environment.
Using uv tool run
uv tool run black script.py
This command runs the specified tool (black in this case) on the target file within a temporary environment created by uv. The virtual environment is stored in uv’s cache, the tool is installed there, and then executed.
Using uvx for shorter execution
uvx black script.py
The uvx command provides a more concise way to run the same tools. Like uv tool run, it creates a temporary cached environment, installs the requested package, and executes it.
By using these commands, we can leverage Python CLI tools efficiently without cluttering the project’s main environment. This results in faster execution, cleaner dependencies, and simplified project management.
6. Conclusion
In this article, we showed how uv streamlines Python project management by combining package installation, virtual environment handling, and Python version control into a single tool, enabling us to create consistent, reproducible environments and simplify workflows across projects.
This was an article on how to manage Python packages with uv.
