uv self update

Update uv to the latest version

uv self update

Update uv to the latest version.

Usage

uv self update [OPTIONS] [TARGET_VERSION]

Description

Update the uv executable to a newer version. By default, updates to the latest available version.

This command:

1. Checks for available versions on GitHub
2. Downloads the specified or latest version
3. Replaces the current uv executable
4. Verifies the installation

The update preserves your current installation location and does not require manual download or installation.

Arguments

[TARGET_VERSION]

Update to the specified version. If not provided, uv will update to the latest version.

# Update to latest version
uv self update

# Update to specific version
uv self update 0.4.0

# Update to specific version with 'v' prefix
uv self update v0.4.0

Options

--token <TOKEN>

A GitHub token for authentication.

A token is not required but can be used to reduce the chance of encountering rate limits when checking for new versions.

uv self update --token ghp_xxxxxxxxxxxx

Environment variable: UV_GITHUB_TOKEN

--dry-run

Run without performing the update.

Shows what would be updated without actually modifying the installation.

uv self update --dry-run

Useful for checking available updates before applying them.

Examples

Update to latest version

uv self update

Expected output:

Downloading uv 0.4.5 (x86_64-unknown-linux-gnu)
Updated uv from 0.4.0 to 0.4.5

Update to specific version

uv self update 0.4.0

Expected output:

Downloading uv 0.4.0 (x86_64-unknown-linux-gnu)
Updated uv from 0.3.5 to 0.4.0

Check for updates without installing

uv self update --dry-run

Expected output:

Would update uv from 0.4.0 to 0.4.5
Run without --dry-run to apply the update

Update with GitHub token

uv self update --token $GITHUB_TOKEN

Uses a GitHub token to avoid rate limiting.

Downgrade to older version

uv self update 0.3.0

You can specify an older version to downgrade if needed.

Use cases

Regular updates

Keep uv up to date with the latest features and bug fixes:

# Check current version
uv --version

# Update to latest
uv self update

# Verify new version
uv --version

CI/CD version control

Pin specific versions in CI pipelines:

name: CI
jobs:
  test:
    steps:
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      
      - name: Update to specific version
        run: uv self update 0.4.0
      
      - name: Verify version
        run: uv --version

Testing new releases

Test new uv versions before rolling out:

# Check what would be updated
uv self update --dry-run

# Update to latest
uv self update

# Test your workflows
uv pip install -r requirements.txt
uv sync

# If issues arise, downgrade
uv self update 0.3.5

Automated update checks

Create a script to check for updates:

#!/bin/bash

# Check for updates
if uv self update --dry-run | grep -q "Would update"; then
    echo "New uv version available!"
    echo "Run 'uv self update' to update"
else
    echo "uv is up to date"
fi

Installation methods and updates

Installed via standalone installer

If you installed uv using the standalone installer:

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

Then uv self update works directly:

uv self update

Installed via pip

If you installed uv via pip, use pip to update:

pip install --upgrade uv

Note: uv self update may not work for pip installations.

Installed via package manager

If you installed via a package manager (Homebrew, etc.), use that package manager:

# Homebrew
brew upgrade uv

# Note: uv self update may not work

Checking your current version

# Show version
uv --version

# Show detailed version information
uv self version

# Show version in JSON format
uv self version --output-format json

GitHub rate limiting

Without authentication, GitHub API requests are rate-limited:

• 60 requests per hour for unauthenticated requests
• 5,000 requests per hour with authentication

To avoid rate limits:

# Create a GitHub token at https://github.com/settings/tokens
export UV_GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Update with token
uv self update

Or:

uv self update --token ghp_xxxxxxxxxxxx

Troubleshooting

Update fails with permission error

# Error: Permission denied

# Solution: Run with appropriate permissions
sudo uv self update

# Or update installation location permissions
sudo chown -R $USER ~/.local/bin/uv
uv self update

Update fails with network error

# Check internet connectivity
curl -I https://github.com

# Try with explicit proxy if needed
export HTTPS_PROXY=http://proxy.example.com:8080
uv self update

Rate limit errors

# Use a GitHub token
export UV_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
uv self update

Verify update succeeded

# Before update
uv --version
# uv 0.4.0

# Perform update
uv self update

# After update
uv --version
# uv 0.4.5

Platform support

Linux

uv self update

Works on all major Linux distributions.

macOS

uv self update

Supports both Intel and Apple Silicon.

Windows

uv self update

Supports Windows 10 and later.

Update notifications

uv may notify you when updates are available:

A new version of uv is available: 0.4.5 (current: 0.4.0)
Run `uv self update` to update

To update:

uv self update

Related commands

• uv self version - Display uv’s version
• uv --version - Show uv version (short form)

Notes

• Updates are downloaded from GitHub releases
• The update preserves your installation location
• Use --dry-run to preview updates without applying them
• GitHub tokens can prevent rate limiting
• For pip installations, use pip install --upgrade uv instead
• For package manager installations (Homebrew, etc.), use the package manager’s update command
• Updates are platform-specific and download the correct binary for your system
• The update process is atomic and safe to interrupt