できない.dev

.nvmrc を置いてもディレクトリ移動時に nvm が自動で切り替わらない

nvm は既定では .nvmrc を自動適用しない。
cd するたびに切り替えたいなら、公式 README の Deeper Shell Integration にあるシェルフックを設定ファイルへ追加する必要がある。

公開: 更新:

症状できない · exit 3
cd project; nvm use
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
N/A: version "v22" is not yet installed.

You need to run `nvm install` to install and use the node version specified in `.nvmrc`.
解決後できた · exit 0
cd project; nvm install
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
Downloading and installing node v22.23.3...
Downloading https://nodejs.org/dist/v22.23.3/node-v22.23.3-linux-x64.tar.xz...
Computing checksum with sha256sum
Checksums matched!
Now using node v22.23.3 (npm v10.9.9)

2026-10-11 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

.nvmrc を置いてもバージョンが切り替わらないのは設定ミスではなく、nvm が既定では cd をフックしないから だ。
.nvmrc は「nvm use を引数なしで実行したときに読まれるファイル」であって、自動適用の仕組みではない。

まずは手動で読ませて、ファイル自体が正しいかを確かめる。

cd path/to/project
nvm use          # .nvmrc(無ければ親ディレクトリを遡って探す)を読む

ディレクトリ移動のたびに自動で切り替えたい場合は、公式 README の Deeper Shell Integration にあるシェル別のフックを自分で設定ファイルへ入れる。

実行例

Node 18 だけを入れた nvm で .nvmrc に 22 と書いて cd しても、node -v は v18.20.8 のままだった。
未インストールの nvm use は終了コード 3 で止まり、nvm install で v22.23.3 が入る。
zsh の chpwd フックを ~/.zshrc に書いた新しいシェルでは、cd するだけで v22.23.3 に切り替わっている。

$ cat -A project/.nvmrc
22$
$ cd project; node -v
v18.20.8
$ cd project; nvm use
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
N/A: version "v22" is not yet installed.
 
You need to run `nvm install` to install and use the node version specified in `.nvmrc`.
$ echo $?
3
$ cd project; nvm install
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
Downloading and installing node v22.23.3...
Downloading https://nodejs.org/dist/v22.23.3/node-v22.23.3-linux-x64.tar.xz...
Computing checksum with sha256sum
Checksums matched!
Now using node v22.23.3 (npm v10.9.9)
$ echo $?
0
$ nvm use 18; cd project; node -v
Now using node v18.20.8 (npm v10.8.2)
v18.20.8
$ nvm use 18; cd project; nvm use; node -v
Now using node v18.20.8 (npm v10.8.2)
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
Now using node v22.23.3 (npm v10.9.9)
v22.23.3
$ cat ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
 
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"
  if [ -n "$nvmrc_path" ]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc
$ source ~/.zshrc; nvm use 18; cd project; node -v
Now using node v18.20.8 (npm v10.8.2)
Found '/tmp/tmp.1qQoH391hj/project/.nvmrc' with version <22>
Now using node v22.23.3 (npm v10.9.9)
v22.23.3

— 2026-10-11 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-11 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. まず手動で nvm use を通す

cat .nvmrc          # 例: 22.11.0 / lts/* / node
nvm use

Found '/path/.nvmrc' with version <...> と出れば読み込み自体は成功している。
公式ドキュメントの .nvmrc(新しいタブで開く) のとおり、ファイルはプロジェクトルートだけでなく親ディレクトリまで遡って探索される。

2. 未インストールなら先に入れる

nvm install      # 引数なしで .nvmrc のバージョンを入れて有効化する

3. 自動切り替えフックを入れる(zsh の例)

~/.zshrc に以下を追記すると、cd のたびに .nvmrc を見て切り替わる。

autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"
  if [ -n "$nvmrc_path" ]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

bash や fish 向けの実装も Deeper Shell Integration(新しいタブで開く) に掲載されている。
自分のシェルに合ったものを使えばよい。

4. ファイルの中身を検証する

cat -A .nvmrc

22.11.0$ のようにバージョン文字列と改行だけになっていれば正常だ。
22.11.0 $ のように行末の半角スペースが見えたら、nvm 0.39.7 では読めないので消す。
全角スペースは 22.11.0M-cM-^@M-^@$ のように見え、0.40.8 でも読めない。

よくある原因

  1. 自動切り替えは nvm の標準機能ではない。
    nvm 本体は chpwd や PROMPT_COMMAND を書き換えず、自動化は利用者側でフックを足す前提で設計されている。
  2. .nvmrc の中身が壊れている。
    全角スペースや v の重複が混ざると、バージョン解決に失敗する。
    nvm 0.39.7 は行末の半角スペースや同じ行のコメントでも失敗したが、0.40.0 以降はどちらも読み飛ばす。
  3. そのバージョンをインストールしていない。
    nvm use は「インストールされていない」と言って終了する。
    エラーメッセージを読まずに「効かない」と判断しているケースが多い。
  4. フックの置き場所が間違っている。
    ~/.zprofile はログインシェルでしか読まれないので、IDE の内蔵ターミナルなど非ログインシェルでは効かない。