ZSH initializer to map "python" => "uv run python" with fallback to global python venv ("uv run --directory default_path python") for one-off / non-project context

python.zsh

# ~/.config/zsh/python.zsh (or wherever you're sourcing from)

# Change if you keep your default env somewhere else
DEFAULT_PY_DIR="${DEFAULT_PY_DIR:-$HOME/Workspace/default_python}"

# Optional: set ZSH_UV_VERBOSE=1 to see what gets executed
_uv_dbg() { [[ -n "$ZSH_UV_VERBOSE" ]] && printf '[uv-shim] %s\n' "$*" >&2; }

# Decide if we're inside a project with a local .venv according to uv
_uv_in_local_venv() {
  # Capture all output; if it contains ".venv" we consider it local
  local out
  out="$(uv python find 2>/dev/null)"
  [[ "$out" == *".venv"* ]]
}

python() {
  if _uv_in_local_venv; then
    _uv_dbg "python → uv run python $*"
    command uv run python "$@"
  else
    _uv_dbg "python → uv run --directory \"$DEFAULT_PY_DIR\" python $*"
    command uv run --directory "$DEFAULT_PY_DIR" python "$@"
  fi
}

pip() {
  if _uv_in_local_venv; then
    _uv_dbg "pip → uv pip $*"
    command uv pip "$@"
  else
    _uv_dbg "pip → uv pip --directory \"$DEFAULT_PY_DIR\" $*"
    command uv pip --directory "$DEFAULT_PY_DIR" "$@"
  fi
}

Python finally has a robust, modern dependency-management solution in uv. However, the lack of a first-class notion of a “global environment” can be cumbersome in usage patterns where users frequently run one-off scripts, ad-hoc REPL sessions, or exploratory notebooks outside a proper project context—especially when they all need access to a common, slowly-changing base set of packages (e.g., numpy, matplotlib, scipy).

This ZSH initializer adds python and pip shell functions that automatically select an environment based on the current working directory. A persistent environment can be created at DEFAULT_PY_DIR, and uv python find is used to detect whether the current directory contains its own local project venv:

If a local venv is found, python maps to uv run python and pip maps to uv pip, using the project’s dependencies.

If not, python maps to uv run --directory $DEFAULT_PY_DIR python and pip maps to uv pip --directory $DEFAULT_PY_DIR, effectively using the persistent “default” environment.

This setup allows you to install packages outside a project context (e.g., pip install numpy scipy) and run one-off python commands while still benefiting from reproducible, uv-managed environments while inside projects. When using editors like VS Code, the default environment can be manually selected as a kernel for ad-hoc notebook work.