Fix “uv: command not found” on Mac, Windows & Linux

You ran the install command. You saw the success message. Then you typed uv --version and got:

uv: command not found

This is the number one reported issue with uv. The installer places the uv binary in a user directory — but most shells don’t check that directory by default. This guide covers exactly why it happens and how to fix it on every platform.

Why It Happens

The uv standalone installer places the binary in a user-specific directory, not a system-wide location:

Linux/macOS:  ~/.local/bin/
Windows:       %USERPROFILE%/.local/bin/

These directories are not on the default shell PATH on most systems. When you type uv, the shell searches the standard system paths — and comes up empty. The fix is to add that directory to your shell’s PATH environment variable.

For context on installing uv in the first place, see the uv getting started guide.

Platform-by-Platform Fixes

Find your platform below and run the two commands shown. The first adds the path to your shell profile, and the second reloads it.

macOS (zsh)

Most modern Macs use zsh as the default shell. Add the path to ~/.zshrc:

# Add ~/.local/bin to PATH for zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# Reload the shell profile
source ~/.zshrc

If you are on an older Mac that still uses bash, use ~/.bashrc or ~/.bash_profile instead of ~/.zshrc.

Linux (bash)

Add the path to ~/.bashrc (or ~/.bash_profile on some distributions):

# Add ~/.local/bin to PATH for bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Reload the shell profile
source ~/.bashrc

If you are on a minimal distro that starts login shells with ~/.bash_profile, add the line there instead and remove it from ~/.bashrc to avoid duplication.

Windows (PowerShell or Command Prompt)

The standalone installer places uv in %USERPROFILE%.localbin (PowerShell and Command Prompt accept both backslashes and forward slashes in paths). You need to add this to your user PATH permanently.

PowerShell (recommended)

Run these commands in an administrative PowerShell window:

# Check if the path is already there
$env:Path -split ';'

# Add the path permanently (user-level)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE.localbin",
    "User"
)

Close and reopen PowerShell for the change to take effect.

Command Prompt

:: Open System Properties → Advanced → Environment Variables
:: In the User variables for your username, select Path and click Edit
:: Add: %USERPROFILE%.localbin
:: Click OK, then restart your terminal

Windows GUI (for any Windows version)

If you prefer clicking over typing:

• Press Win + R, type sysdm.cpl, press Enter
• Click Environment Variables
• In the top section (User variables), find and select Path, then click Edit
• Click New and add: %USERPROFILE%.localbin
• Click OK on all windows
• Close and reopen your terminal

VS Code Integrated Terminal

Even after fixing your system PATH, VS Code’s integrated terminal sometimes doesn’t inherit it — especially on Windows. VS Code launches its shell as a child process with a restricted environment, and the PATH change may not propagate.

Quick Reload Fix

Before trying VS Code settings, first try the simplest fix: close VS Code completely and reopen it. A new window gets a fresh environment. If that doesn’t work, proceed to the settings below.

Set terminal.integrated.env on Windows

Open .vscode/settings.json in your workspace (or global VS Code settings) and add:

{
    "terminal.integrated.env.windows": {
        "PATH": "${env:USERPROFILE}/.local/bin;${env:PATH}"
    }
}

Reload the terminal after saving: open a new terminal tab (Ctrl + Shift + `) and try uv --version.

Enable Shell Integration on macOS/Linux

On macOS and Linux, VS Code’s integrated terminal may use a stripped-down shell environment. Enable shell integration to ensure proper PATH resolution:

{
    "terminal.integrated.shellIntegration.enabled": true
}

This makes VS Code’s terminal execute your shell’s login scripts fully, picking up any PATH modifications you made.

Tip: If uv works in your normal terminal but not in VS Code, the issue is definitely VS Code’s environment. The terminal.integrated.env setting above is the targeted fix.

Verify the Fix

After adding the path and restarting your terminal (or opening a new tab), run:

uv --version

If you see a version number (e.g., uv 0.5.3), you are done. If you still get command not found, verify the binary actually exists:

# Linux/macOS
ls ~/.local/bin/uv

# Windows Command Prompt
dir "%USERPROFILE%.localbinuv.exe"

If the file is missing, run the installer again — the initial install may have been interrupted:

# Reinstall uv (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reinstall uv (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Docker PATH Fix

When uv is installed inside a Docker container (for example, using the standalone installer in a Dockerfile), the same PATH issue appears. The uv binary lands in /root/.local/bin which is not on the container’s default PATH.

# syntax=docker/dockerfile:1
FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Add uv's bin directory to PATH for all subsequent RUN/CMD layers
ENV PATH="/root/.local/bin:$PATH"

# Now uv is available in any RUN, CMD, or ENTRYPOINT command
RUN uv --version

The ENV PATH=... line must appear after the COPY --from line. If you put it before, the layer order causes the variable to be reset. Note that the ghcr.io/astral-sh/uv:latest image already has uv on its own PATH, so when you copy it with COPY --from, you are copying the binary, not the environment.

Common mistake: Adding ENV PATH before the COPY --from. Docker evaluates ENV at build time, so it must come after the binary is copied in. A common pattern is to put ENV PATH on its own line right after the COPY.

Prevention: Keep uv Updated

Once uv is on your PATH, keeping it updated is one command:

# Check current version
uv --version

# Update to the latest release
uv self update

uv self update only works when uv was installed via the standalone installer (the curl | sh script or PowerShell installer). If you installed uv via a package manager (brew, apt, pip install uv), use that package manager’s upgrade command instead.

Shell Restart Habit

Whenever you install a new tool that modifies PATH, get in the habit of closing and reopening your terminal. This ensures the shell picks up the new environment cleanly, avoiding stale session state. On macOS especially, some tools write to ~/.zprofile which is only read by login shells — opening a new terminal tab (not just a new split pane) triggers a fresh login.

Summary

The uv: command not found error is a PATH issue, not an installation issue. The fix is always the same two steps:

• Add the directory to PATH: ~/.local/bin on Linux/macOS, %USERPROFILE%.localbin on Windows
• Reload the shell: open a new terminal tab or restart VS Code

For quick reference, here is the one-liner that fixes it on Linux and macOS:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc