Back to Details

zsh-path-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zsh PATH Management Skill

Zsh PATH 管理指南

This skill provides comprehensive guidance for managing PATH environment variables in zsh, including troubleshooting missing commands, adding new tools, and organizing shell configuration.
本文档提供了在zsh中管理PATH环境变量的全面指导，包括排查命令缺失问题、添加新工具以及整理shell配置等内容。

When to Use This Skill

适用场景

Use this skill when:
  • Getting "command not found" errors for installed tools
  • Adding new tools to PATH (bun, nvm, cargo, go, Python venv, etc.)
  • Validating and auditing current PATH entries
  • Organizing PATH configuration between .zshrc and .zshrc.local
  • Troubleshooting shell startup issues related to PATH
  • Setting up version managers (nvm, pyenv, rbenv)
在以下场景中使用本指南：
  • 已安装的工具出现“command not found”错误
  • 将新工具（如bun、nvm、cargo、go、Python venv等）添加到PATH
  • 验证和审计当前PATH条目
  • 在.zshrc和.zshrc.local之间整理PATH配置
  • 排查与PATH相关的shell启动问题
  • 配置版本管理器（nvm、pyenv、rbenv）

Diagnostic Commands

诊断命令

Check Current PATH

查看当前PATH

bash
undefined
bash
undefined

List all PATH entries

List all PATH entries

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

Check if specific command is in PATH

Check if specific command is in PATH

which bun 2>/dev/null || echo "bun not found in PATH"
which bun 2>/dev/null || echo "bun not found in PATH"

Find where a command is installed

Find where a command is installed

command -v node type -a python
undefined
command -v node type -a python
undefined

Validate PATH Entries

验证PATH条目

bash
undefined
bash
undefined

Check for broken/non-existent PATH entries

Check for broken/non-existent PATH entries

echo $PATH | tr ':' '\n' | while read p; do [[ -d "$p" ]] || echo "MISSING: $p" done
echo $PATH | tr ':' '\n' | while read p; do [[ -d "$p" ]] || echo "MISSING: $p" done

Check for duplicate PATH entries

Check for duplicate PATH entries

echo $PATH | tr ':' '\n' | sort | uniq -d
undefined
echo $PATH | tr ':' '\n' | sort | uniq -d
undefined

Common Tool PATH Configurations

常见工具的PATH配置

Bun (JavaScript runtime)

Bun（JavaScript 运行时）

bash
undefined
bash
undefined

Add to .zshrc

Add to .zshrc

export BUN_INSTALL="$HOME/.bun" export PATH="$BUN_INSTALL/bin:$PATH"

Default location: `~/.bun/bin/bun`
export BUN_INSTALL="$HOME/.bun" export PATH="$BUN_INSTALL/bin:$PATH"

默认位置：`~/.bun/bin/bun`

NVM (Node Version Manager)

NVM（Node 版本管理器）

bash
undefined
bash
undefined

Add to .zshrc

Add to .zshrc

export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

Default location: `~/.nvm/`

**Note:** NVM is a shell function, not a binary. It modifies PATH dynamically to point to the active Node version.
export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

默认位置：`~/.nvm/`

**注意：** NVM是一个shell函数，而非二进制文件。它会动态修改PATH以指向当前激活的Node版本。

Python Virtual Environment

Python 虚拟环境

bash
undefined
bash
undefined

Add to .zshrc for global tools venv

Add to .zshrc for global tools venv

export PATH="$HOME/.venv/tools3/bin:$PATH"
export PATH="$HOME/.venv/tools3/bin:$PATH"

For pyenv

For pyenv

export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"
undefined
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"
undefined

Rust/Cargo

Rust/Cargo

bash
undefined
bash
undefined

Add to .zshrc

Add to .zshrc

export PATH="$HOME/.cargo/bin:$PATH"
undefined
export PATH="$HOME/.cargo/bin:$PATH"
undefined

Go

Go

bash
undefined
bash
undefined

Add to .zshrc

Add to .zshrc

export GOPATH="$HOME/go" export PATH="$GOPATH/bin:$PATH"
undefined
export GOPATH="$HOME/go" export PATH="$GOPATH/bin:$PATH"
undefined

Homebrew (macOS)

Homebrew（macOS）

bash
undefined
bash
undefined

Intel Mac

Intel Mac

export PATH="/usr/local/bin:$PATH"
export PATH="/usr/local/bin:$PATH"

Apple Silicon Mac

Apple Silicon Mac

export PATH="/opt/homebrew/bin:$PATH" eval "$(/opt/homebrew/bin/brew shellenv)"
undefined
export PATH="/opt/homebrew/bin:$PATH" eval "$(/opt/homebrew/bin/brew shellenv)"
undefined

Local bin directories

本地bin目录

bash
undefined
bash
undefined

User-local binaries

User-local binaries

export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/bin:$PATH"
undefined
export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/bin:$PATH"
undefined

File Organization Best Practices

文件组织最佳实践

.zshrc (Team/Shared Configuration)

.zshrc（团队/共享配置）

Keep in .zshrc:
  • Oh My Zsh configuration
  • Common team aliases
  • Standard PATH additions (homebrew, local bin)
  • Plugin configuration
bash
undefined
建议在.zshrc中保存：
  • Oh My Zsh配置
  • 团队通用别名
  • 标准PATH添加项（如homebrew、本地bin）
  • 插件配置
bash
undefined

===== ZSH-TOOL MANAGED SECTION BEGIN =====

===== ZSH-TOOL MANAGED SECTION BEGIN =====

Team-wide PATH modifications

Team-wide PATH modifications

export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/bin:$PATH"
export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/bin:$PATH"

Bun

Bun

export BUN_INSTALL="$HOME/.bun" export PATH="$BUN_INSTALL/bin:$PATH"
export BUN_INSTALL="$HOME/.bun" export PATH="$BUN_INSTALL/bin:$PATH"

NVM

NVM

export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

===== ZSH-TOOL MANAGED SECTION END =====

===== ZSH-TOOL MANAGED SECTION END =====

Load local customizations

Load local customizations

[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local
undefined
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local
undefined

.zshrc.local (Personal/Machine-Specific)

.zshrc.local（个人/机器专属配置）

Keep in .zshrc.local:
  • Machine-specific PATH entries
  • Personal tool configurations
  • Experimental settings
  • Integrations that may override keybindings
bash
undefined
建议在.zshrc.local中保存：
  • 机器专属的PATH条目
  • 个人工具配置
  • 实验性设置
  • 可能覆盖按键绑定的集成项
bash
undefined

Machine-specific tools

Machine-specific tools

export PATH="/opt/custom-tool/bin:$PATH"
export PATH="/opt/custom-tool/bin:$PATH"

Personal integrations

Personal integrations

if command -v atuin >/dev/null 2>&1; then eval "$(atuin init zsh)" fi
undefined
if command -v atuin >/dev/null 2>&1; then eval "$(atuin init zsh)" fi
undefined

PATH Order Matters

PATH的顺序至关重要

PATH is searched left-to-right. First match wins.
bash
undefined
PATH的搜索顺序是从左到右，第一个匹配的命令会被优先使用。
bash
undefined

This order means ~/.local/bin takes priority over system bins

This order means ~/.local/bin takes priority over system bins

export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
undefined
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
undefined

Recommended PATH Order

推荐的PATH顺序

  1. Project-specific bins (added by direnv)
  2. User local bins (
    ~/.local/bin
    , 
    ~/bin
    )
  3. Language version managers (nvm, pyenv, rbenv)
  4. Package managers (homebrew, cargo)
  5. System paths (
    /usr/local/bin
    , 
    /usr/bin
    )
  1. 项目专属bin目录（由direnv添加）
  2. 用户本地bin目录（
    ~/.local/bin
    、
    ~/bin
    ）
  3. 语言版本管理器（nvm、pyenv、rbenv）
  4. 包管理器（homebrew、cargo）
  5. 系统路径（
    /usr/local/bin
    、
    /usr/bin
    ）

Troubleshooting

问题排查

Command Not Found After Installation

安装后出现Command Not Found错误

bash
undefined
bash
undefined

1. Find where tool was installed

1. Find where tool was installed

ls -la ~/.bun/bin/bun 2>/dev/null ls -la ~/.cargo/bin/rustc 2>/dev/null ls -la ~/.nvm/versions/node/*/bin/node 2>/dev/null
ls -la ~/.bun/bin/bun 2>/dev/null ls -la ~/.cargo/bin/rustc 2>/dev/null ls -la ~/.nvm/versions/node/*/bin/node 2>/dev/null

2. Check if PATH includes the directory

2. Check if PATH includes the directory

echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"
echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"

3. Add missing PATH entry to .zshrc

3. Add missing PATH entry to .zshrc

4. Reload shell

4. Reload shell

source ~/.zshrc
source ~/.zshrc

or

or

exec $SHELL
undefined
exec $SHELL
undefined

PATH Changes Not Taking Effect

PATH修改未生效

bash
undefined
bash
undefined

Check which file sets the variable

Check which file sets the variable

grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null
grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null

Source the correct file

Source the correct file

source ~/.zshrc
source ~/.zshrc

Or start fresh shell

Or start fresh shell

exec $SHELL
undefined
exec $SHELL
undefined

Startup Hook Errors

启动钩子错误

Common causes:
  • Missing PATH entries for tools used in hooks
  • Broken references to non-existent directories
  • Version managers not finding expected versions
bash
undefined
常见原因：
  • 启动钩子中使用的工具对应的PATH条目缺失
  • 引用了不存在的目录
  • 版本管理器未找到预期的版本
bash
undefined

Debug startup

Debug startup

zsh -x 2>&1 | head -100
zsh -x 2>&1 | head -100

Check for errors in specific config

Check for errors in specific config

bash -n ~/.zshrc
undefined
bash -n ~/.zshrc
undefined

Duplicate PATH Entries

重复的PATH条目

bash
undefined
bash
undefined

Remove duplicates (add to .zshrc)

Remove duplicates (add to .zshrc)

typeset -U PATH path
undefined
typeset -U PATH path
undefined

Verification Commands

验证命令

After making PATH changes:
bash
undefined
修改PATH后，执行以下命令验证：
bash
undefined

Reload configuration

Reload configuration

source ~/.zshrc
source ~/.zshrc

Verify tool is accessible

Verify tool is accessible

which bun && bun --version which node && node --version command -v nvm && nvm --version
which bun && bun --version which node && node --version command -v nvm && nvm --version

Verify PATH includes new entries

Verify PATH includes new entries

echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"
undefined
echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"
undefined

Quick Reference

快速参考

ToolPATH EntryCheck Command
bun
$HOME/.bun/bin
bun --version
nvm
$NVM_DIR/versions/node/*/bin
nvm --version
cargo
$HOME/.cargo/bin
cargo --version
go
$GOPATH/bin
go version
pyenv
$PYENV_ROOT/bin
pyenv --version
brew (ARM)
/opt/homebrew/bin
brew --version
brew (Intel)
/usr/local/bin
brew --version
工具PATH条目验证命令
bun
$HOME/.bun/bin
bun --version
nvm
$NVM_DIR/versions/node/*/bin
nvm --version
cargo
$HOME/.cargo/bin
cargo --version
go
$GOPATH/bin
go version
pyenv
$PYENV_ROOT/bin
pyenv --version
brew (ARM)
/opt/homebrew/bin
brew --version
brew (Intel)
/usr/local/bin
brew --version

Common Patterns

常见配置模式

Conditional PATH Addition

条件式PATH添加

bash
undefined
bash
undefined

Only add if directory exists

Only add if directory exists

[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"
[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"

Only add if command not already available

Only add if command not already available

command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"
undefined
command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"
undefined

Lazy Loading for Faster Startup

延迟加载以加快启动速度

bash
undefined
bash
undefined

Lazy load nvm (faster shell startup)

Lazy load nvm (faster shell startup)

lazy_load_nvm() { unset -f nvm node npm npx export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" } nvm() { lazy_load_nvm && nvm "$@"; } node() { lazy_load_nvm && node "$@"; } npm() { lazy_load_nvm && npm "$@"; } npx() { lazy_load_nvm && npx "$@"; }
undefined
lazy_load_nvm() { unset -f nvm node npm npx export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" } nvm() { lazy_load_nvm && nvm "$@"; } node() { lazy_load_nvm && node "$@"; } npm() { lazy_load_nvm && npm "$@"; } npx() { lazy_load_nvm && npx "$@"; }
undefined