Skip to main content

​
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

curl -LsSf https://astral.sh/uv/install.sh | sh
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: 
brew install 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: 
uv --completion bash > ~/.uv-completion.bash
echo 'source ~/.uv-completion.bash' >> ~/.bashrc

​
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: 
uv self update

​
Uninstalling uv

Remove uv from your system: 
rm $(which uv)
# Also remove from shell profile if added
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us