Installation

Install uv using the standalone installer, pip, pipx, package managers, or from source.

Installation

Install uv on macOS, Linux, or Windows using your preferred method. The standalone installer is recommended for most users.

Standalone installer

The standalone installer downloads and installs uv without requiring Rust or Python.

1. Run the installer

   macOS and Linux

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   The installer downloads the latest uv release and installs it to your system.

2. Verify the installation

   uv --version
   

   You should see the installed uv version number.

3. Check available commands

   uv --help
   

   This displays all available uv commands and options.

uv installed via the standalone installer can update itself:

uv self update

Install with pip

Install uv using pip if you prefer to manage it within your Python environment:

1. Install via pip

   pip install uv
   

   This installs uv as a Python package in your current environment.

2. Verify the installation

   uv --version
   

When installed via pip, use pip install --upgrade uv to update instead of uv self update.

Install with pipx

pipx installs uv in an isolated environment while making it globally accessible:

1. Install via pipx

   pipx install uv
   

   pipx creates an isolated environment for uv, preventing dependency conflicts.

2. Verify the installation

   uv --version
   
3. Update uv

   pipx upgrade uv
   

pipx is recommended if you want uv isolated from your system Python but don’t want to use the standalone installer.

Package managers

Install uv using your operating system’s package manager:

Homebrew (macOS/Linux)

brew install uv

conda install -c conda-forge uv

pacman -S uv

apk add uv

After installing via a package manager, verify the installation:

uv --version

Install from source

Build uv from source if you need the latest development version or want to contribute:

1. Install Rust

   Install Rust using rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   On Ubuntu/Debian, also install build essentials:

   sudo apt install build-essential
   

   On Fedora:

   sudo dnf install gcc
   
2. Clone the repository

   git clone https://github.com/astral-sh/uv.git
   cd uv
   
3. Build and install

   cargo build --release
   

   The compiled binary will be available at target/release/uv.

4. Add to PATH

   Move the binary to a directory in your PATH or add the target directory to your PATH:

   # Option 1: Copy to a directory in PATH
   sudo cp target/release/uv /usr/local/bin/
   
   # Option 2: Add to PATH in your shell profile
   echo 'export PATH="$HOME/uv/target/release:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   
5. Verify the installation

   uv --version
   

Building from source requires Rust and a C compiler. This method is primarily for development and testing.

Platform support

uv officially supports:

• macOS: x86_64 and ARM64 (Apple Silicon)
• Linux: x86_64, ARM64, and other architectures
• Windows: x86_64

For detailed platform compatibility information, see the platform support documentation.

Post-installation setup

After installing uv, you’re ready to start using it. No additional configuration is required for basic usage.

Shell completion

Enable shell completion for enhanced command-line experience:

Bash

uv --completion bash > ~/.uv-completion.bash
echo 'source ~/.uv-completion.bash' >> ~/.bashrc

uv --completion zsh > ~/.zsh/completion/_uv

uv --completion fish > ~/.config/fish/completions/uv.fish

uv --completion powershell >> $PROFILE

Configuration

uv works without configuration, but you can customize behavior using:

• Environment variables: Set UV_* variables to control behavior
• Configuration files: Create a uv.toml or pyproject.toml with uv settings
• Command-line flags: Override defaults for specific commands

Start with the defaults and add configuration as needed. uv is designed to work well out of the box.

Updating uv

Keep uv up to date to get the latest features and improvements:

Standalone installer

uv self update

pip install --upgrade uv

pipx upgrade uv

brew upgrade uv

conda update -c conda-forge uv

Uninstalling uv

Remove uv from your system:

Standalone installer (Unix)

rm $(which uv)
# Also remove from shell profile if added

Remove-Item (Get-Command uv).Path

pip uninstall uv

pipx uninstall uv

brew uninstall uv

conda remove uv

Uninstalling uv doesn’t remove cached packages. To remove the cache, delete the ~/.cache/uv directory (or %LOCALAPPDATA%\uv\cache on Windows).

Troubleshooting

Permission denied errors

If you encounter permission errors during installation:

# Use sudo for system-wide installation (Unix)
sudo curl -LsSf https://astral.sh/uv/install.sh | sh

# Or install to user directory
curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --no-modify-path

Command not found

If uv command is not found after installation:

1. Check if the installation directory is in your PATH:

   echo $PATH
   

2. Add the uv installation directory to your PATH in your shell profile:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

Antivirus interference (Windows)

Some antivirus software may block the installer. Temporarily disable it or add an exception for the uv installer.

Next steps

Quick start

Create your first project and learn essential commands.

Command reference

Explore all available commands with uv --help.