Skip to main content

​
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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us