uv tool update-shell

Ensure that the tool executable directory is on the PATH

uv tool update-shell

Ensure that the tool executable directory is on the PATH.

Aliases

• uv tool ensurepath - Alternative name for the same command

Usage

uv tool update-shell
uv tool ensurepath

Description

If the tool executable directory is not present on the PATH, uv will attempt to add it to the relevant shell configuration files.

If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, uv will exit with an error.

The tool executable directory is determined according to the XDG standard and can be retrieved with uv tool dir --bin.

After running this command, you need to restart your shell or source your shell configuration file for the changes to take effect.

When to Use

Run this command when:

• You’ve just installed your first tool with uv tool install
• You get “command not found” errors after installing a tool
• You’ve installed uv and want to ensure tools can be run from anywhere
• You’re setting up a new development environment

Examples

Add tool directory to PATH

uv tool update-shell

Expected output:

Added uv tool directory to PATH in ~/.bashrc
Restart your shell or run: source ~/.bashrc

Apply changes immediately

# Run update-shell
uv tool update-shell

# Then reload your shell configuration
source ~/.bashrc  # For bash
source ~/.zshrc   # For zsh

Check if update is needed

# Check if tool directory is already in PATH
echo $PATH | grep -q "$(uv tool dir --bin)" && echo "Already in PATH" || echo "Not in PATH"

# If not in PATH, run update-shell
if ! echo $PATH | grep -q "$(uv tool dir --bin)"; then
    uv tool update-shell
fi

What Gets Modified

The command modifies your shell configuration file by adding the tool directory to your PATH. The specific file depends on your shell:

Bash

Modifies ~/.bashrc (Linux) or ~/.bash_profile (macOS):

# Added by uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"

Zsh

Modifies ~/.zshrc:

# Added by uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"

Fish

Modifies ~/.config/fish/config.fish:

# Added by uv tool update-shell
set -gx PATH $HOME/.local/bin $PATH

PowerShell (Windows)

Modifies PowerShell profile:

# Added by uv tool update-shell
$env:PATH = "$env:LOCALAPPDATA\uv\bin;$env:PATH"

Tool Executable Directory

The tool executable directory location varies by platform:

Unix/Linux/macOS

Determined by the following environment variables, in order:

1. $UV_TOOL_BIN_DIR (if set)
2. $XDG_BIN_HOME (if set)
3. $XDG_DATA_HOME/../bin (if XDG_DATA_HOME is set)
4. $HOME/.local/bin (default)

Windows

• %LOCALAPPDATA%\uv\bin

Finding your tool directory

# Show the executable directory
uv tool dir --bin

# Show the tools environment directory
uv tool dir

Behavior Details

Already configured

If the configuration is already present, uv will report this:

uv tool update-shell
# Output: Tool directory is already configured in PATH

Configuration exists but not in current PATH

If the shell configuration file contains the correct entry but your current PATH doesn’t include it:

uv tool update-shell
# Output: Error: PATH configuration exists in ~/.bashrc but is not active in current shell
# Restart your shell or run: source ~/.bashrc

Multiple shells

If you use multiple shells, run the command in each:

# In bash
bash -c "uv tool update-shell"

# In zsh
zsh -c "uv tool update-shell"

Verification

After running uv tool update-shell and restarting your shell:

Check PATH includes tool directory

echo $PATH | grep "$(uv tool dir --bin)"

Test with an installed tool

# Install a tool
uv tool install ruff

# Verify it's accessible
which ruff
ruff --version

Check shell configuration

# View the added configuration
grep -A2 "Added by uv" ~/.bashrc

Troubleshooting

Changes not taking effect

If tools are still not found after running update-shell:

# 1. Verify the command ran successfully
uv tool update-shell

# 2. Restart your shell completely (close and reopen terminal)
# OR source the configuration file
source ~/.bashrc  # bash
source ~/.zshrc   # zsh

# 3. Verify PATH is updated
echo $PATH | grep uv

# 4. Test a tool
which ruff

Permission errors

If you get permission errors when modifying shell configuration:

# Check file permissions
ls -la ~/.bashrc

# Fix if needed (be careful!)
chmod 644 ~/.bashrc

Multiple PATH entries

If you’ve run update-shell multiple times, you might have duplicate entries:

# View duplicates
grep -n "uv tool" ~/.bashrc

# Manually edit to remove duplicates
$EDITOR ~/.bashrc

Custom shell location

If you use a non-standard shell configuration location:

# Manually add to your custom config file
echo 'export PATH="'$(uv tool dir --bin)':$PATH"' >> ~/.my_custom_config

Container/Docker environments

In containerized environments, you might need to add the PATH directly:

# Dockerfile
ENV PATH="/root/.local/bin:$PATH"

Or in your shell:

# Add to current session
export PATH="$(uv tool dir --bin):$PATH"

Tool directory on non-standard location

If using a custom tool directory via UV_TOOL_BIN_DIR:

# Set custom location
export UV_TOOL_BIN_DIR="/custom/path/to/bin"

# Then run update-shell
uv tool update-shell

# Verify the custom path is used
uv tool dir --bin

Best Practices

First-time setup

When setting up uv on a new system:

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

# 2. Update shell configuration
uv tool update-shell

# 3. Restart shell or source configuration
source ~/.bashrc

# 4. Install your tools
uv tool install ruff black mypy

# 5. Verify
ruff --version

Team onboarding

Include in your project’s setup documentation:

# Setup script for new developers
#!/bin/bash

set -e

echo "Setting up uv..."

# Install uv if not present
if ! command -v uv &> /dev/null; then
    curl -LsSf https://astral.sh/uv/install.sh | sh
fi

# Configure PATH
uv tool update-shell

echo "Setup complete! Please restart your shell."

CI/CD environments

In CI/CD, explicitly set PATH instead of using update-shell:

# GitHub Actions example
- name: Set up uv tools
  run: |
    echo "$HOME/.local/bin" >> $GITHUB_PATH

Manual Configuration

If you prefer to manually configure your PATH or update-shell doesn’t work for your setup:

# Get the tool directory
TOOL_BIN_DIR=$(uv tool dir --bin)

# Add to your shell configuration
echo "export PATH=\"$TOOL_BIN_DIR:\$PATH\"" >> ~/.bashrc

# Source the configuration
source ~/.bashrc

See Also

• uv tool install - Install tools
• uv tool dir - Show tool directories
• uv tool list - List installed tools