uv

🚀 uv – Python Package and Project Manager

uv is a high-performance Python package manager and project toolchain, written in Rust. It consolidates functionalities from multiple tools into a single, fast, and efficient interface, aiming to replace pip, pipx, poetry, pyenv, virtualenv, pip-tools, twine, and more.

🔧 Key Features

• Unified Tooling: Combines functionalities of multiple tools into one.
• Blazing Fast: 10–100x faster than pip.
• Cross-Platform: Supports macOS, Linux, and Windows.
• Minimal Dependencies: Single binary with no external dependencies.
• Comprehensive Project Management: Handles pyproject.toml, lockfiles, and more.
• Python Version Management: Install and manage multiple Python versions.
• Tool Installation: Install and run Python-based tools like ruff, black, etc.
• Script Execution: Run standalone Python scripts with inline dependencies.

⚙️ Usage

Python Version Management

• Install Python Versions:

  uv python install 3.10.7

• List Installed Versions:

  uv python list

• Pin Python Version for Project:

  uv python pin 3.10.7

• Uninstall Python Version:

  uv python uninstall 3.10.7

Virtual Environments

• Create a Virtual Environment:

  uv venv

• Create with Specific Python Version:

  uv venv --python 3.10

• Activate the Environment:

  source .venv/bin/activate  # macOS/Linux
  .venv\Scripts\activate     # Windows

• Install Dependencies:

  uv pip install -r requirements.txt

• Freeze Installed Packages:

  uv pip freeze > requirements.txt

Project Management

• Initialize a New Project:

  uv init my-project

• Add a Dependency:

  uv add requests

• Remove a Dependency:

  uv remove requests

• Sync Dependencies:

  uv sync

• Generate Lockfile:

  uv lock

• Run Project Scripts:

  uv run script.py

• Build Project:

  uv build

• Publish Project:

  uv publish

Tool Management

• Install a Tool:

  uv tool install black

• Uninstall a Tool:

  uv tool uninstall black

• Run a Tool:

  uv tool run black .

• List Installed Tools:

  uv tool list

Running Python Scripts with Inline Dependencies

Add Inline Metadata to Your Script

To begin, you’ll need to add metadata to your Python script to specify the required dependencies and Python version. This can be done using the uv add --script command:

uv add --script your_script.py 'requests' 'numpy'

This command will modify your script to include a special comment block at the top, indicating the dependencies:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "numpy",
# ]
# ///

Make the Script Executable

To run your script directly from the command line, add a shebang line at the very top of your script:

#!/usr/bin/env -S uv run --script

Ensure the script is executable:

chmod +x your_script.py

Run the Script

Now, you can execute your script directly:

./your_script.py

The first time you run it, uv will create an isolated virtual environment, install the specified dependencies, and execute the script. On subsequent runs, the environment is cached, leading to near-instant execution times .

📦 Compatibility with Existing Tools

uv is designed to be compatible with existing Python tools and workflows:

• pyproject.toml Support: Fully supports PEP 621-compliant pyproject.toml files.
• requirements.txt Compatibility: Works seamlessly with requirements.txt files.
• pip Interface: Provides a familiar pip-like interface for package management.
• pipx Replacement: Can install and run Python-based tools globally, replacing pipx.
• pyenv Alternative: Manages multiple Python versions without the need for pyenv.

🧪 Example

Here’s a typical workflow using uv:

# Initialize a new project
uv init my-project
 
# Navigate into the project directory
cd my-project
 
# Create a virtual environment
uv venv
 
# Activate the environment
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows
 
# Add dependencies
uv add requests
 
# Generate lockfile
uv lock
 
# Install dependencies
uv sync
 
# Run the project script
uv run script.py