> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv self update

> Update uv to the latest version

# uv self update

Update uv to the latest version.

## Usage

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
uv self update --dry-run
```

Useful for checking available updates before applying them.

## Examples

### Update to latest version

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
uv self update --token $GITHUB_TOKEN
```

Uses a GitHub token to avoid rate limiting.

### Downgrade to older version

```bash theme={null}
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:

```bash theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
#!/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:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then `uv self update` works directly:

```bash theme={null}
uv self update
```

### Installed via pip

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

```bash theme={null}
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:

```bash theme={null}
# Homebrew
brew upgrade uv

# Note: uv self update may not work
```

## Checking your current version

```bash theme={null}
# 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:

```bash theme={null}
# Create a GitHub token at https://github.com/settings/tokens
export UV_GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Update with token
uv self update
```

Or:

```bash theme={null}
uv self update --token ghp_xxxxxxxxxxxx
```

## Troubleshooting

### Update fails with permission error

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Use a GitHub token
export UV_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
uv self update
```

### Verify update succeeded

```bash theme={null}
# Before update
uv --version
# uv 0.4.0

# Perform update
uv self update

# After update
uv --version
# uv 0.4.5
```

## Platform support

### Linux

```bash theme={null}
uv self update
```

Works on all major Linux distributions.

### macOS

```bash theme={null}
uv self update
```

Supports both Intel and Apple Silicon.

### Windows

```powershell theme={null}
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:

```bash theme={null}
uv self update
```

## Related commands

* [`uv self version`](/cli/self-version) - Display uv's version
* [`uv --version`](/cli/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