---
obj: application
repo: https://github.com/astral-sh/uv
website: https://docs.astral.sh/uv
rev: 2025-06-05
---

# 🚀 `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:**

  ```bash
  uv python install 3.10.7
  ```

* **List Installed Versions:**

  ```bash
  uv python list
  ```

* **Pin Python Version for Project:**

  ```bash
  uv python pin 3.10.7
  ```

* **Uninstall Python Version:**

  ```bash
  uv python uninstall 3.10.7
  ```

### Virtual Environments

* **Create a Virtual Environment:**

  ```bash
  uv venv
  ```

* **Create with Specific Python Version:**

  ```bash
  uv venv --python 3.10
  ```

* **Activate the Environment:**

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

* **Install Dependencies:**

  ```bash
  uv pip install -r requirements.txt
  ```

* **Freeze Installed Packages:**

  ```bash
  uv pip freeze > requirements.txt
  ```

### Project Management

* **Initialize a New Project:**

  ```bash
  uv init my-project
  ```

* **Add a Dependency:**

  ```bash
  uv add requests
  ```

* **Remove a Dependency:**

  ```bash
  uv remove requests
  ```

* **Sync Dependencies:**

  ```bash
  uv sync
  ```

* **Generate Lockfile:**

  ```bash
  uv lock
  ```

* **Run Project Scripts:**

  ```bash
  uv run script.py
  ```

* **Build Project:**

  ```bash
  uv build
  ```

* **Publish Project:**

  ```bash
  uv publish
  ```

### Tool Management

* **Install a Tool:**

  ```bash
  uv tool install black
  ```

* **Uninstall a Tool:**

  ```bash
  uv tool uninstall black
  ```

* **Run a Tool:**

  ```bash
  uv tool run black .
  ```

* **List Installed Tools:**

  ```bash
  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:

```bash
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:

```python
# /// 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:

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

Ensure the script is executable:

```bash
chmod +x your_script.py
```

#### **Run the Script**
Now, you can execute your script directly:
```bash
./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`:

```bash
# 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
```