> ## 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.

# Installation

> Install uv using the standalone installer, pip, pipx, package managers, or from source.

# 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.

<Steps>
  <Step title="Run the installer">
    <CodeGroup>
      ```bash macOS and Linux theme={null}
      curl -LsSf https://astral.sh/uv/install.sh | sh
      ```

      ```powershell Windows theme={null}
      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
      ```
    </CodeGroup>

    The installer downloads the latest uv release and installs it to your system.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    uv --version
    ```

    You should see the installed uv version number.
  </Step>

  <Step title="Check available commands">
    ```bash theme={null}
    uv --help
    ```

    This displays all available uv commands and options.
  </Step>
</Steps>

<Tip>
  uv installed via the standalone installer can update itself:

  ```bash theme={null}
  uv self update
  ```
</Tip>

## Install with pip

Install uv using pip if you prefer to manage it within your Python environment:

<Steps>
  <Step title="Install via pip">
    ```bash theme={null}
    pip install uv
    ```

    This installs uv as a Python package in your current environment.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    uv --version
    ```
  </Step>
</Steps>

<Warning>
  When installed via pip, use `pip install --upgrade uv` to update instead of `uv self update`.
</Warning>

## Install with pipx

pipx installs uv in an isolated environment while making it globally accessible:

<Steps>
  <Step title="Install via pipx">
    ```bash theme={null}
    pipx install uv
    ```

    pipx creates an isolated environment for uv, preventing dependency conflicts.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    uv --version
    ```
  </Step>

  <Step title="Update uv">
    ```bash theme={null}
    pipx upgrade uv
    ```
  </Step>
</Steps>

<Note>
  pipx is recommended if you want uv isolated from your system Python but don't want to use the standalone installer.
</Note>

## Package managers

Install uv using your operating system's package manager:

<CodeGroup>
  ```bash Homebrew (macOS/Linux) theme={null}
  brew install uv
  ```

  ```bash Conda theme={null}
  conda install -c conda-forge uv
  ```

  ```bash Arch Linux theme={null}
  pacman -S uv
  ```

  ```bash Alpine Linux theme={null}
  apk add uv
  ```
</CodeGroup>

<Tip>
  After installing via a package manager, verify the installation:

  ```bash theme={null}
  uv --version
  ```
</Tip>

## Install from source

Build uv from source if you need the latest development version or want to contribute:

<Steps>
  <Step title="Install Rust">
    Install Rust using rustup:

    ```bash theme={null}
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```

    On Ubuntu/Debian, also install build essentials:

    ```bash theme={null}
    sudo apt install build-essential
    ```

    On Fedora:

    ```bash theme={null}
    sudo dnf install gcc
    ```
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/astral-sh/uv.git
    cd uv
    ```
  </Step>

  <Step title="Build and install">
    ```bash theme={null}
    cargo build --release
    ```

    The compiled binary will be available at `target/release/uv`.
  </Step>

  <Step title="Add to PATH">
    Move the binary to a directory in your PATH or add the target directory to your PATH:

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

  <Step title="Verify the installation">
    ```bash theme={null}
    uv --version
    ```
  </Step>
</Steps>

<Warning>
  Building from source requires Rust and a C compiler. This method is primarily for development and testing.
</Warning>

## Platform support

uv officially supports:

* **macOS**: x86\_64 and ARM64 (Apple Silicon)
* **Linux**: x86\_64, ARM64, and other architectures
* **Windows**: x86\_64

<Note>
  For detailed platform compatibility information, see the [platform support documentation](https://docs.astral.sh/uv/reference/platforms/).
</Note>

## 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:

<CodeGroup>
  ```bash Bash theme={null}
  uv --completion bash > ~/.uv-completion.bash
  echo 'source ~/.uv-completion.bash' >> ~/.bashrc
  ```

  ```bash Zsh theme={null}
  uv --completion zsh > ~/.zsh/completion/_uv
  ```

  ```bash Fish theme={null}
  uv --completion fish > ~/.config/fish/completions/uv.fish
  ```

  ```powershell PowerShell theme={null}
  uv --completion powershell >> $PROFILE
  ```
</CodeGroup>

### 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

<Tip>
  Start with the defaults and add configuration as needed. uv is designed to work well out of the box.
</Tip>

## Updating uv

Keep uv up to date to get the latest features and improvements:

<CodeGroup>
  ```bash Standalone installer theme={null}
  uv self update
  ```

  ```bash pip theme={null}
  pip install --upgrade uv
  ```

  ```bash pipx theme={null}
  pipx upgrade uv
  ```

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

  ```bash Conda theme={null}
  conda update -c conda-forge uv
  ```
</CodeGroup>

## Uninstalling uv

Remove uv from your system:

<CodeGroup>
  ```bash Standalone installer (Unix) theme={null}
  rm $(which uv)
  # Also remove from shell profile if added
  ```

  ```powershell Standalone installer (Windows) theme={null}
  Remove-Item (Get-Command uv).Path
  ```

  ```bash pip theme={null}
  pip uninstall uv
  ```

  ```bash pipx theme={null}
  pipx uninstall uv
  ```

  ```bash Homebrew theme={null}
  brew uninstall uv
  ```

  ```bash Conda theme={null}
  conda remove uv
  ```
</CodeGroup>

<Note>
  Uninstalling uv doesn't remove cached packages. To remove the cache, delete the `~/.cache/uv` directory (or `%LOCALAPPDATA%\uv\cache` on Windows).
</Note>

## Troubleshooting

### Permission denied errors

If you encounter permission errors during installation:

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

2. Add the uv installation directory to your PATH in your shell profile:
   ```bash theme={null}
   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

<CardGroup cols={2}>
  <Card title="Quick start" icon="rocket" href="/quickstart">
    Create your first project and learn essential commands.
  </Card>

  <Card title="Command reference" icon="terminal">
    Explore all available commands with `uv --help`.
  </Card>
</CardGroup>