How to Install uv on Linux

uv is an extremely fast Python package and project manager, written in Rust. It serves as a drop-in replacement for pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more. If you’re using Linux and want to supercharge your Python development workflow, this guide will walk you through installing uv.

System Requirements

Before we begin, make sure you have:

• Linux Distribution: Any modern Linux distribution (Ubuntu, Debian, Fedora, Arch, etc.)
• Architecture: Compatible with x86_64, ARM64, and other supported architectures
• Internet connection: To download the installer and packages
• Shell access: Terminal or command line interface
• Optional: Python 3.8+ (if installing via pip/pipx)

Step 1: Install uv Using the Standalone Installer (Recommended)

The easiest and most reliable way to install uv is using the official standalone installer:

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

If your system doesn’t have curl, use wget:

wget -qO- https://astral.sh/uv/install.sh | sh

To install a specific version:

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

What this installer does:

• Downloads the appropriate uv binary for your system
• Installs it to ~/.local/bin/uv
• Adds uv to your PATH automatically
• Sets up shell completion (optional)

Step 2: Verify Installation

After installation, restart your terminal or source your shell profile:

source ~/.bashrc  # or ~/.zshrc for Zsh users

Verify that uv is installed correctly:

uv --version

You should see output like:

uv 0.7.13 (4e1f459a6 2024-11-28)

Test uv functionality:

uv --help

Step 3: Set Up Shell Autocompletion (Optional)

Enable shell autocompletion for better command-line experience:

For Bash users:

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

For Zsh users:

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

For Fish users:

echo 'uv generate-shell-completion fish | source' >> ~/.config/fish/config.fish

Enable uvx autocompletion as well:

For Bash:

echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc

For Zsh:

echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

Apply the changes:

source ~/.bashrc  # or source ~/.zshrc for Zsh

Step 4: Test uv with Your First Project

Let’s create a simple Python project to verify everything works:

# Create a new project
uv init hello-uv
cd hello-uv

# Add a dependency
uv add requests

# Run the project
uv run python -c "import requests; print('uv is working!')"

Alternative Installation Methods

Method 2: Install via Package Managers

Homebrew (if available on Linux):

brew install uv

Cargo (requires Rust toolchain):

cargo install --git https://github.com/astral-sh/uv uv

Method 3: Install via Python Package Managers

Using pipx (recommended for Python-based installation):

# Install pipx first if not available
sudo apt-get install pipx  # Ubuntu/Debian
# or
sudo dnf install pipx      # Fedora

# Install uv with pipx
pipx install uv

Using pip (less recommended):

pip install uv

Method 4: Download from GitHub Releases

You can also download prebuilt binaries directly:

# Check the latest release at https://github.com/astral-sh/uv/releases
wget https://github.com/astral-sh/uv/releases/download/0.7.13/uv-x86_64-unknown-linux-gnu.tar.gz
tar -xzf uv-x86_64-unknown-linux-gnu.tar.gz
sudo mv uv-x86_64-unknown-linux-gnu/uv /usr/local/bin/

What uv Provides

Your uv installation includes powerful features for Python development:

Python Version Management

• Install Python versions: uv python install 3.12
• List available versions: uv python list
• Pin project versions: uv python pin 3.11

Project Management

• Create projects: uv init my-project
• Add dependencies: uv add numpy pandas
• Sync environments: uv sync
• Run commands: uv run python script.py

Tool Management

• Run tools temporarily: uvx black .
• Install tools globally: uv tool install ruff
• List installed tools: uv tool list

Package Management (pip replacement)

• Install packages: uv pip install requests
• Create virtual environments: uv venv
• Compile requirements: uv pip compile requirements.in

Important Notes

PATH Configuration: The standalone installer automatically configures your PATH. If uv command isn’t found, restart your terminal or manually source your shell configuration.

Performance: uv is significantly faster than pip – often 10-100x faster for common operations like dependency resolution and package installation.

Compatibility: uv maintains compatibility with pip, pip-tools, and other Python packaging tools while providing enhanced functionality.

Self-Updates: When installed via the standalone installer, uv can update itself:

uv self update

Getting Started with uv

Create Your First Project

# Initialize a new project
uv init my-awesome-project
cd my-awesome-project

# Add some dependencies
uv add fastapi uvicorn

# Add development dependencies
uv add --dev pytest black ruff

# Run your application
uv run python -m uvicorn main:app --reload

Use uv as a pip Replacement

# Create a virtual environment
uv venv

# Activate it (traditional way)
source .venv/bin/activate

# Install packages (much faster than pip)
uv pip install django

# Or use uv run to automatically manage the environment
uv run python manage.py runserver

Run Tools Without Installing

# Run black formatter temporarily
uvx black .

# Run pytest on a project
uvx pytest

# Run jupyter notebook
uvx jupyter notebook

Troubleshooting

Common issues and solutions:

1. uv command not found:
   • Restart your terminal
   • Check that ~/.local/bin is in your PATH
   • Run source ~/.bashrc or equivalent
2. Permission errors:
   • Never run uv with sudo
   • Ensure ~/.local/bin is writable by your user
3. Slow operations:
   • Clear uv cache: uv cache clean
   • Check internet connection for package downloads
4. Python version issues:
   • Install Python with uv: uv python install 3.12
   • Pin project Python version: uv python pin 3.12
5. Package conflicts:
   • Use uv pip check to diagnose issues
   • Create fresh virtual environment: uv venv --force

Advanced Configuration

Configure uv behavior with environment variables:

# Set custom cache directory
export UV_CACHE_DIR="$HOME/.cache/uv"

# Disable automatic virtual environment creation
export UV_PROJECT_ENVIRONMENT=""

# Use specific Python version globally
export UV_PYTHON="3.12"

Create a configuration file at ~/.config/uv/uv.toml:

[pip]
index-url = "https://pypi.org/simple"
extra-index-url = ["https://pypi.org/simple"]

[tool.uv]

dev-dependencies = [ „pytest>=6.0“, „black>=22.0“, „ruff>=0.1.0“, ]

Migrating from Other Tools

From pip:

• Replace pip install with uv pip install
• Replace pip freeze with uv pip freeze
• Use uv venv instead of python -m venv

From poetry:

• Use uv init instead of poetry new
• Use uv add instead of poetry add
• Use uv run instead of poetry run

From pipenv:

• Use uv venv + uv pip install instead of pipenv install
• Use uv run instead of pipenv run

Uninstalling uv

If you need to remove uv from your system:

1. Clean up stored data (optional):

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

2. Remove uv binaries:

rm ~/.local/bin/uv ~/.local/bin/uvx

3. Remove PATH modifications from your shell configuration file (.bashrc, .zshrc, etc.)
4. Remove configuration:

rm -rf ~/.config/uv

Next Steps

Now that uv is installed on your Linux system, you can:

• Read the official guides: Explore uv’s comprehensive documentation
• Try the tutorials: Learn project management, dependency handling, and tool usage
• Migrate existing projects: Convert pip, poetry, or pipenv projects to uv
• Explore advanced features: Multi-platform builds, workspace management, and publishing
• Join the community: Participate in discussions on GitHub and Discord

Performance Benefits

uv provides significant performance improvements over traditional Python tools:

• Dependency resolution: 10-100x faster than pip
• Package installation: Parallel downloads and installations
• Virtual environment creation: Near-instantaneous
• Project setup: Faster than poetry, pipenv, and conda

Why Choose uv?

Speed: Written in Rust for maximum performance Compatibility: Drop-in replacement for existing tools Modern: Built with current Python packaging standards Comprehensive: Handles the entire Python development lifecycle Active Development: Rapidly evolving with frequent updates

---

Having trouble with your uv installation on Linux? Leave a comment and we’ll help you troubleshoot!