zsh: command not found: pnpm — починка PATH на macOS

Поставила pnpm на новый MacBook, открыла терминал, написала pnpm -v, и получила:

zsh: command not found: pnpm

Сообщение значит ровно то, что говорит: zsh не нашёл бинарник pnpm ни в одной из директорий, перечисленных в переменной PATH. Дальше дело за тем, чтобы понять — где он лежит и почему туда не дотягивается shell.

На macOS это очень типичная история, потому что у zsh при первом запуске PATH собирается из нескольких файлов, и куда установился pnpm — зависит от способа установки. Покажу, как разбираю.

Где может лежать pnpm

В зависимости от того, чем ставила, бинарник окажется в одном из этих мест:

• Через установщик с pnpm.io (curl -fsSL https://get.pnpm.io/install.sh | sh -) — обычно ~/.local/share/pnpm/ или ~/Library/pnpm/.
• Через npm install -g pnpm — там же, где npm-globals: $(npm prefix -g)/bin/pnpm.
• Через Corepack (включён в Node 16.10+) — в директории Node, обычно $(dirname $(which node))/pnpm.
• Через Homebrew — /opt/homebrew/bin/pnpm (Apple Silicon) или /usr/local/bin/pnpm (Intel).

Найти можно так:

find ~ /usr/local /opt/homebrew -name pnpm 2>/dev/null | head -5

Что в PATH сейчас

echo $PATH

Это длинная строка с двоеточиями: /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin. Если в выводе нет директории, в которой реально лежит pnpm — shell его не найдёт.

Проверить, что pnpm запускается напрямую по полному пути:

~/Library/pnpm/pnpm -v

Если эта команда работает, проблема — только PATH.

Где нужно прописать PATH в zsh

На macOS логин-shell — zsh. Он читает несколько файлов в строгом порядке:

• /etc/zshenv
• ~/.zshenv
• /etc/zprofile (только для login shell)
• ~/.zprofile (только для login shell)
• /etc/zshrc
• ~/.zshrc

На macOS иногда есть штука /usr/libexec/path_helper, которая сбрасывает PATH в /etc/zprofile. Поэтому если PATH прописать в ~/.zshenv, а потом path_helper в /etc/zprofile переопределит, твой путь окажется не первым.

В моей практике самая надёжная схема — экспорт нужных директорий в конец ~/.zshrc. Тогда они всегда побеждают:

# pnpm
export PNPM_HOME="$HOME/Library/pnpm"
case ":$PATH:" in
  *":$PNPM_HOME:"*) ;;
  *) export PATH="$PNPM_HOME:$PATH" ;;
esac
# end pnpm

Этот блок установщик pnpm обычно сам дописывает в ~/.zshrc при установке. Если нет — допиши.

После правки — перезапустить shell:

exec zsh -l

Или открыть новый терминал.

Если ставила через Corepack

Corepack — встроенный в Node 16.10+ менеджер пакетных менеджеров. Включается:

corepack enable
corepack prepare pnpm@latest --activate

После этого pnpm живёт рядом с node — в той же директории. Если node работает, pnpm должен работать тоже. Если получаешь command not found от corepack-версии — значит сам node не в PATH, и нужно сначала разобраться с ним.

Если ставила через Homebrew

brew install pnpm

Homebrew на Apple Silicon ставит в /opt/homebrew/bin, на Intel — в /usr/local/bin. Обе директории должны быть в PATH сразу после установки brew, но если ты вручную меняла PATH и обрезала — могло пропасть.

Восстановить рекомендуемый brew shell-environment:

/opt/homebrew/bin/brew shellenv
# вывод выглядит примерно так:
# export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
# ...

Этот вывод можно дописать в ~/.zprofile:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

Особый случай: nvm

Если у тебя стоит nvm и ты переключаешь версии Node, путь к глобальным npm-пакетам меняется при каждом переключении. Соответственно, и pnpm, установленный через npm i -g pnpm в одной версии Node, недоступен в другой.

Пути:

• либо ставить pnpm не через npm, а через corepack или официальный installer;
• либо ставить отдельно для каждой нужной версии Node;
• либо использовать fnm вместо nvm и настроить его так, чтобы он не менял пути глобальных пакетов.

Я лично пользуюсь corepack — это самая беспроблемная схема: pnpm живёт рядом с node, версия фиксируется через packageManager в package.json.

Как проверить, что починилось

which pnpm
pnpm -v

which pnpm покажет полный путь к бинарнику, который shell нашёл. pnpm -v — версию. Если оба работают — всё.

Если совсем ничего не работает

Запусти shell в режиме отладки и посмотри, какие файлы он реально читает:

zsh -ix 2>&1 | head -50

В выводе видно, что вообще выполняется при старте. Иногда находишь сюрпризы — например, чужой .zshrc.pre-oh-my-zsh, который перезаписывает PATH.

Чек-лист

• Найти, где реально лежит pnpm.
• Запустить его по полному пути — работает?
• Добавить директорию в PATH через ~/.zshrc или ~/.zprofile.
• Перезапустить shell.
• Проверить через which pnpm и pnpm -v.

Точно такая же логика работает для любого command not found на macOS: yarn, bun, gh, что угодно. Узнаёшь, где бинарник, прописываешь PATH правильно — и больше не спотыкаешься.