Debug uv python $PATH problems

Sep 26, 2025

This quick fix cheatsheet is for myself & other pythonistas with the following versioning preferences:

• Use uv as the de facto python version manager
• Always use the latest stable version when calling python
• Have peace of mind that running python will always call a uv-installed version instead of homebrew or another system version

I've added commands to troubleshoot obnoxious $PATH problems and a code block at the bottom to update to new versions without breaking the expectations above.

The Key 🔑

I have the following at the very bottom of my ~/.zshrc to ensure that uv python installs are always found first:

# KEEP AT BOTTOM!
export PATH="$HOME/.local/bin:$PATH"

Troubleshoot $PATH 🔍

which python3

Should be ~/.local/bin/ for versions installed via uv.

uv python update-shell

Quick fix if ~/.local/bin isn't on your $PATH.

echo $PATH | tr ':' '\n'

Output paths in your $PATH env var line by line for ease of reading. This helped me spot duplicates and odd orderings which prevented uv installs from taking precedence. I used this so often I created a path alias for it.

Install New Versions 🔄

# Might as well
uv self update

# Find the latest stable version
uv python list

# Install it and update python & python3 symlinks
uv python install 3.XX.X --default

#python