.nvmrc を置いてもディレクトリ移動時に nvm が自動で切り替わらない
nvm は既定では .nvmrc を自動適用しない。cd するたびに切り替えたいなら、公式 README の Deeper Shell Integration にあるシェルフックを設定ファイルへ追加する必要がある。
公開: 更新:
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`.
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:20Debian 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 useFound '/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-nvmrcbash や fish 向けの実装も Deeper Shell Integration(新しいタブで開く) に掲載されている。
自分のシェルに合ったものを使えばよい。
4. ファイルの中身を検証する
cat -A .nvmrc22.11.0$ のようにバージョン文字列と改行だけになっていれば正常だ。22.11.0 $ のように行末の半角スペースが見えたら、nvm 0.39.7 では読めないので消す。
全角スペースは 22.11.0M-cM-^@M-^@$ のように見え、0.40.8 でも読めない。
よくある原因
- 自動切り替えは nvm の標準機能ではない。
nvm 本体はchpwdやPROMPT_COMMANDを書き換えず、自動化は利用者側でフックを足す前提で設計されている。 .nvmrcの中身が壊れている。
全角スペースやvの重複が混ざると、バージョン解決に失敗する。
nvm 0.39.7 は行末の半角スペースや同じ行のコメントでも失敗したが、0.40.0 以降はどちらも読み飛ばす。- そのバージョンをインストールしていない。
nvm useは「インストールされていない」と言って終了する。
エラーメッセージを読まずに「効かない」と判断しているケースが多い。 - フックの置き場所が間違っている。
~/.zprofileはログインシェルでしか読まれないので、IDE の内蔵ターミナルなど非ログインシェルでは効かない。