zsh-path

Zsh PATH 管理スキル

このスキルでは、zsh の PATH 環境変数の管理について、コマンドが見つからない場合のトラブルシューティング、新しいツールの追加、シェル設定の整理などを含む包括的なガイダンスを提供します。

このスキルを使う場面

次のような場合に、このスキルを使用してください：

• インストール済みのツールで「command not found」エラーが発生する
• PATH に新しいツールを追加する（bun、nvm、cargo、go、Python venv など）
• 現在の PATH エントリーを検証し、監査する
• .zshrc と .zshrc.local の PATH 設定を整理する
• PATH に関連するシェルの起動時の問題をトラブルシューティングする
• バージョンマネージャー（nvm、pyenv、rbenv）をセットアップする

診断コマンド

現在の PATH を確認する

# List all PATH entries
echo $PATH | tr ':' '\n'

# Check if specific command is in PATH
which bun 2>/dev/null || echo "bun not found in PATH"

# Find where a command is installed
command -v node
type -a python

PATH エントリーを検証する

# Check for broken/non-existent PATH entries
echo $PATH | tr ':' '\n' | while read p; do
  [[ -d "$p" ]] || echo "MISSING: $p"
done

# Check for duplicate PATH entries
echo $PATH | tr ':' '\n' | sort | uniq -d

よく使うツールの PATH 設定

Bun（JavaScript ランタイム）

# Add to .zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

デフォルトの場所：~/.bun/bin/bun

NVM（Node バージョンマネージャー）

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

デフォルトの場所：~/.nvm/

注： NVM はバイナリではなく、シェル関数です。アクティブな Node のバージョンを指すように、PATH を動的に変更します。

Python 仮想環境

# Add to .zshrc for global tools venv
export PATH="$HOME/.venv/tools3/bin:$PATH"

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

Rust/Cargo

# Add to .zshrc
export PATH="$HOME/.cargo/bin:$PATH"

Go

# Add to .zshrc
export GOPATH="$HOME/go"
export PATH="$GOPATH/bin:$PATH"

Homebrew（macOS）

# Intel Mac
export PATH="/usr/local/bin:$PATH"

# Apple Silicon Mac
export PATH="/opt/homebrew/bin:$PATH"
eval "$(/opt/homebrew/bin/brew shellenv)"

ローカルの bin ディレクトリ

# User-local binaries
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

ファイル構成のベストプラクティス

.zshrc（チーム／共有設定）

.zshrc には次の設定を記述します：

• Oh My Zsh の設定
• チームで共通のエイリアス
• 標準的な PATH の追加（homebrew、ローカルの bin）
• プラグインの設定

# ===== ZSH-TOOL MANAGED SECTION BEGIN =====
# Team-wide PATH modifications
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

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

# NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# ===== ZSH-TOOL MANAGED SECTION END =====

# Load local customizations
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local

.zshrc.local（個人／マシン固有の設定）

.zshrc.local には次の設定を記述します：

• マシン固有の PATH エントリー
• 個人用ツールの設定
• 実験的な設定
• キーバインドを上書きする可能性のある連携機能

# Machine-specific tools
export PATH="/opt/custom-tool/bin:$PATH"

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

PATH の順序が重要です

PATH は左から右へ検索されます。最初に見つかったものが優先されます。

# This order means ~/.local/bin takes priority over system bins
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"

推奨する PATH の順序

1. プロジェクト固有の bin（direnv によって追加）
2. ユーザーのローカル bin（~/.local/bin、~/bin）
3. 言語のバージョンマネージャー（nvm、pyenv、rbenv）
4. パッケージマネージャー（homebrew、cargo）
5. システムパス（/usr/local/bin、/usr/bin）

トラブルシューティング

インストール後にコマンドが見つからない

# 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

# 2. Check if PATH includes the directory
echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"

# 3. Add missing PATH entry to .zshrc

# 4. Reload shell
source ~/.zshrc
# or
exec $SHELL

PATH の変更が反映されない

# Check which file sets the variable
grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null

# Source the correct file
source ~/.zshrc

# Or start fresh shell
exec $SHELL

起動フックのエラー

よくある原因：

• フックで使用するツールの PATH エントリーがない
• 存在しないディレクトリへの参照が壊れている
• バージョンマネージャーが想定されるバージョンを見つけられない

# Debug startup
zsh -x 2>&1 | head -100

# Check for errors in specific config
bash -n ~/.zshrc

PATH エントリーの重複

# Remove duplicates (add to .zshrc)
typeset -U PATH path

確認コマンド

PATH を変更した後：

# Reload configuration
source ~/.zshrc

# Verify tool is accessible
which bun && bun --version
which node && node --version
command -v nvm && nvm --version

# Verify PATH includes new entries
echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"

クイックリファレンス

ツール	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

よくあるパターン

条件付き PATH 追加

# Only add if directory exists
[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"

# Only add if command not already available
command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"

起動を高速化する遅延読み込み

# 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 "$@"; }

---

注意点

• path= 配列と PATH= 環境変数：typeset -U を使わずに片方へ代入すると、一意性が失われます： 数時間後に古いエントリが重複して現れます。.zshrc の早い段階で一度 typeset -U path PATH を実行すると、両者が連動し、自動的に重複が排除されます。
• .zprofile はログインシェルでのみ実行され、.zshrc は対話型シェルで実行されます： Homebrew のインストーラーは eval "$(brew shellenv)" を .zprofile に追加するよう提案しますが、ログインシェルではない対話型シェル（Linux の多くのターミナルセッション）では完全に見落とされます。サブシェルでコマンドが見つからない場合は、.zshrc にも同じ設定を追加してください。
• NVM はバイナリではなくシェル関数です — which node の表示はあてになりません： nvm use の後、which node は ~/.nvm/versions/node/vXX/bin/node を表示しますが、nvm.sh を再度読み込むまでは、新しいサブシェルでは何も表示されないことがあります。bash -c 経由で実行されるスクリプトは、NVM を完全に迂回します。
• NVM の遅延読み込みは、シバンでの npm 呼び出しを遅くします： #!/usr/bin/env node で始まるスクリプトは新しいシェルを起動し、そのシェルが .zshrc を読み込み、さらに NVM を遅延読み込みするため、スクリプトを呼び出すたびに 500ms 以上かかります。Node スクリプトを多数実行する場合は、NVM を先に読み込んでください。
• source ~/.zshrc を実行しても、以前に追加した PATH は取り消されません： 再読み込みすると重複排除なしで追加されるため、実行するたびに PATH が増えていきます。PATH の変更をテストするときは、source ではなく、必ず新しいシェル（exec zsh）を起動してください。
• Apple Silicon の Homebrew は /opt/homebrew/bin にあるため、Intel バイナリからは見えません： Rosetta モードのターミナル（arch -x86_64 zsh）では、代わりに /usr/local/bin が表示されます。同じマシンでも、Homebrew のプレフィックスとツールチェーンがそれぞれ異なります。