npm min-release-age の挙動詳細

Arganoの松田です。この記事では、npm の min-release-age オプションの挙動について詳しく解説します。

min-release-age とは

min-release-age は、npm パッケージのリリース後に一定期間が経過するまで、最新バージョンをインストールしないようにするオプションです。これにより、リリース直後の不具合や悪意のあるコード（サプライチェーン攻撃など）からプロジェクトを保護することができます。

特に最近では npm パッケージに対する攻撃が増加しているため、リリース後すぐに最新バージョンを使用することのリスクが高まっています。min-release-age を設定することで、これらのリスクを軽減できます。

https://docs.npmjs.com/cli/v11/using-npm/config#min-release-age

pnpm や yarn など、他のパッケージマネージャーにも同様の機能があります。

設定方法

min-release-age は、プロジェクトの .npmrc ファイルに以下のように設定します。

この例では、リリース後 7 日が経過するまで最新バージョンをインストールしないように設定しています。

min-release-age=7 # 単位は日数

挙動の詳細

環境

Node.js : v24.14.1
npm : 11.12.1

min-release-age の挙動を調べるため、新規 npm プロジェクトを作成します。

mkdir npm-min-release-age-test
cd npm-min-release-age-test
npm init -y

次に、min-release-age を 14 日に設定します。

echo "min-release-age=14" > .npmrc

1. 特定のバージョンを指定した場合の挙動

この状態で、記事執筆時点で最新の lodash パッケージをバージョン指定でインストールしてみます。

# 4.18.1 は記事執筆時点で12日前にリリースされたバージョン
npm install lodash@4.18.1

そうすると、以下のようなエラーになります。(一部省略)

npm error code ETARGET
npm error notarget No matching version found for lodash@4.18.1 with a date before 3/31/2026, 5:45:05 PM.
npm error notarget In most cases you or one of your dependencies are requesting a package version that doesn't exist.

12日前にリリースされたバージョン 4.18.1 は、設定した「14日」を満たしていないため、インストールが拒否されることがわかります。

次に、14日以上前にリリースされたバージョンをインストールしてみます。

# 4.17.23 は記事執筆時点で3ヶ月前にリリースされたバージョン
npm install lodash@4.17.23

この場合は、期間の条件をクリアしているため正常にインストールされます。

2. バージョン指定なし（@latest）の場合の挙動

検証のため、一度モジュールを削除します。

rm -rf node_modules package-lock.json package.json
npm init -y

バージョンを指定せずに（あるいは明示的に @latest をつけて）インストールしてみます。

npm install lodash
# または npm install lodash@latest

この場合、エラーにはならず、インストールが成功します。ただし、インストールされたバージョンを package.json で確認すると、最新版（4.18.1）ではなく、「14日以上経過している中で最も新しいバージョン（4.17.23）」 が自動的に選択されてインストールされます。

つまり、min-release-age を設定しておけば、安全な期間が経過した最新バージョンへ自動的にフォールバックしてくれます。

3. 後から設定した場合の挙動

では、既にパッケージがインストールされているプロジェクトに対し、後から min-release-age を設定した場合はどうでしょうか。検証のため、一度 min-release-age を無効化して最新版をインストールします。

rm -rf node_modules package-lock.json
echo "# min-release-age=14" > .npmrc

この状態で、先ほどは期間制限で弾かれた最新バージョンをインストールします。

npm install lodash@4.18.1

（無効化されているのでインストールに成功します）

その後、min-release-age を再度有効にしてみます。

echo "min-release-age=14" > .npmrc

この状態で node_modules を削除し、再度 npm install を実行してみます。

rm -rf node_modules
npm install

そうすると、エラーにはならずインストールが成功します。

これは、npm install 実行時に package-lock.json が存在する場合、そこに記録されているバージョン解決が優先されるためです。

4. 緊急パッチを今すぐ当てたい場合（バイパス方法）

min-release-age を設定していると、1つ困ったケースが発生する可能性があります。それは**「深刻な脆弱性が発見され、今日リリースされたばかりの緊急修正パッチ（最新版）を今すぐインストールしたい」**という状況です。

設定が有効なままだと、指定した日数が経過するまでこの緊急パッチをインストールできず、プロジェクトが脆弱な状態のまま放置されてしまいます。

このような場合は、npm install コマンド実行時に --min-release-age=0 オプションを渡すことで、.npmrc の設定を一時的に上書き（バイパス）できます。

# 深刻な脆弱性が修正された最新パッチ(例: 4.18.2)が今日リリースされたと仮定
# CLIオプションで一時的に日数を 0 にしてインストール
npm install lodash@4.18.2 --min-release-age=0

npm の設定は .npmrc よりもコマンドラインのオプションが優先されるため、この方法を使えば緊急時でも即座に最新版を取り込むことが可能です。

まとめ

min-release-age を活用することで、開発体験を大きく損なうことなく、リリース直後のパッケージ起因のトラブルを防ぐことができます。プロジェクトのセキュリティポリシーに合わせて、ぜひ設定を検討してみてください。