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

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

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

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

```bash theme={null}
uv tool update-shell
```

Expected output:

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

### Apply changes immediately

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

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

```bash theme={null}
# Added by uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"
```

### Zsh

Modifies `~/.zshrc`:

```zsh theme={null}
# Added by uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"
```

### Fish

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

```fish theme={null}
# Added by uv tool update-shell
set -gx PATH $HOME/.local/bin $PATH
```

### PowerShell (Windows)

Modifies PowerShell profile:

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

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

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

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

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

```bash theme={null}
echo $PATH | grep "$(uv tool dir --bin)"
```

### Test with an installed tool

```bash theme={null}
# Install a tool
uv tool install ruff

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

### Check shell configuration

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

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

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

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

```bash theme={null}
# 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 theme={null}
# Dockerfile
ENV PATH="/root/.local/bin:$PATH"
```

Or in your shell:

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

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

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

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

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

```bash theme={null}
# 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](/cli/tool-install) - Install tools
* [uv tool dir](/cli/tool-dir) - Show tool directories
* [uv tool list](/cli/tool-list) - List installed tools