pnpmでネットワークなしにinstallする手順|12.21のstore addでGitHubやtarballのURLの依存も入るように、ERR_PNPM_NO_OFFLINE_METAの対処も

pnpm 12.21.0でGitHubやtarballのURLの依存もオフラインで入れられるようになった

JavaScriptのパッケージマネージャーpnpmの開発チームが、2026年11月13日(協定世界時)にpnpm 12.21.0を公開しました(12.21.0のリリースノート)。中心の変更は、ネットワークにつながない環境で入れられる依存の種類が増えたことです。

pnpmには、別の方法で取得したパッケージのtarball(パッケージを固めたファイル)を、pnpmのストア(パッケージを保存する場所)へ先に入れておくpnpm store addがあります。12.20.0までは、この方法でオフラインで入れられたのはレジストリーのパッケージだけでした。12.21.0からは、package.jsonにtarballのURLで書いた依存と、GitHubのリポジトリーを指す依存のうち、ロックファイルにtarballのURLとintegrity(ファイルの中身を確かめるためのハッシュ値)が記録されるものも入ります。変更を入れたプルリクエストは、NixやFlatpakのように、ネットワークを使わずにビルドする仕組みを想定しています(#18000)。

この記事では、ネットワークを切ったDockerのコンテナーで、pnpm 12.20.0と12.21.0の結果を比べました。手順に沿って試すと、pnpm 12の既定の設定のままでは、tarballを用意してもinstallがロックファイルの確認で止まることも分かりました。その原因と、開発チームが案内している進め方もあわせて説明します。

要点

12.21.0なら、レジストリー・tarballのURL・GitHubの3種類の依存が、ネットワークなしで入った

ネットワークを切ったコンテナーで、pnpm 12.20.0と12.21.0を同じ手順で比べた結果です。

12.21.0で入るようになった依存

tarballのURLで書いた依存と、GitHubの依存

12.20.0は、この2種類で「snapshot not present in local store」と止まりました。ロックファイルにtype: gitと記録される依存は、12.21.0でも対象外です。

既定の設定で止まる

12.20.0も12.21.0も、既定の設定ではinstallがロックファイルの確認で止まる

12.21.0では、ネットワークのある環境で先にロックファイルを確かめ、オフラインのinstallに--trust-lockfileを付けると3種類とも入りました。

実行する場所

pnpm store addは、プロジェクトのフォルダーで実行する

プロジェクトの外で実行すると、12.21.0でもGitHubの依存が入りませんでした。外から実行するなら--dirでプロジェクトを指定します。

ネットワークなしでinstallするまでの4つの手順

オフラインのinstallは、ネットワークのある環境での準備と、ネットワークのない環境での作業に分かれます。pnpmのドキュメントのstore addの説明と、後の節で紹介する開発チームの案内に沿うと、次の4つの手順になります(pnpm storeのドキュメント)。

手順1(ネットワークあり)

ロックファイルを作る

pnpm install --lockfile-onlyでpnpm-lock.yamlを作ります。依存ごとの版とintegrityが記録されます。

手順2(ネットワークあり)

pnpm install --frozen-lockfile --lockfile-onlyでロックファイルを確かめる

ロックファイルの各項目がminimumReleaseAgeなどの決まりに合うかを、ネットワークのある環境で先に確かめます。

手順3(ネットワークあり)

ロックファイルにある依存のtarballを取得し、1つのフォルダーに置く

取得の方法は問いません。ビルドの仕組みが持つ取得の機能や、ふつうのダウンロードで集めます。

手順4(ネットワークなし)

プロジェクトのフォルダーでstore addしてから、オフラインでinstallする

pnpm store add ./tarballsのあとにpnpm install --frozen-lockfile --offline --trust-lockfileを実行します。

tarballのURLとGitHubの依存は、手順1のロックファイルに、取得先のURLがtarballとして記録されます。手元で試したプロジェクトでは、GitHubの公開リポジトリーの依存(github:jonschlinkert/is-number#7.0.0)が、codeload.github.comのURLとintegrity付きで記録されました。12.21.0がGitHubの依存をオフラインで入れるのは、このようにintegrityが記録された場合です。

is-number@https://codeload.github.com/jonschlinkert/is-number/tar.gz/98e8ff1da1a89f93d1397a24d7413ed15421c139:
  resolution: {gitHosted: true, integrity: sha512-i6H8exN6…, tarball: https://codeload.github.com/jonschlinkert/is-number/tar.gz/98e8ff1…}
  version: 7.0.0

pnpm 12.20.0で作ったpnpm-lock.yamlのGitHubの依存の部分(一部を省略)。

一方、リポジトリーをcloneして取る依存は、ロックファイルにtype: gitとして、commitとリポジトリーの場所だけが記録されます。#18000はこの種類を対象外としています。手元でも、ローカルのGitのリポジトリーを指す依存(git+file:)はこの形で記録され、store addでtarballを入れてもオフラインのinstallはGitから取りに行って止まりました。自前のGitのサーバーを使う依存は、自分のロックファイルでどちらの形かを先に確かめます。

12.20.0ではtarballのURLとGitHubの依存がオフラインで入らなかった

手元では、3種類の依存を持つプロジェクトを用意しました。レジストリーのms@2.1.3、tarballのURLで書いたis-odd(https://registry.yarnpkg.com/is-odd/-/is-odd-3.0.1.tgz)、GitHubのis-number(7.0.0)です。4つのtarball(is-oddの依存のis-number 6.0.0を含む)をpnpmを使わずに取得し、ネットワークを切ったコンテナーでstore addからinstallまでを実行しました。

3種類をまとめたプロジェクトでは、12.21.0は3種類とも入り、12.20.0はinstallが止まって何も入りませんでした。

依存の書き方 pnpm 12.20.0 pnpm 12.21.0
3種類をまとめたプロジェクト止まった(何も入らなかった)3種類とも入った
レジストリーの依存だけ("ms": "2.1.3")入った入った
GitHubの依存だけ(is-number 7.0.0)止まった(snapshot not present in local store)入った

ネットワークを切ったDockerのコンテナー(Node.js 24.22.3)で、minimumReleaseAgeを0にして実行した結果。12.21.0のレジストリーの行は、3種類をまとめたプロジェクトの結果。2026年11月17日に確認。

12.20.0は、3種類をまとめたプロジェクトで、手元の実行ではtarballのURLの依存のところで次のように止まりました。store addはtarballを取り込んだのに、installがそのtarballを使えていません。

Failed to fetch tarball for https://registry.yarnpkg.com/is-odd/-/is-odd-3.0.1.tgz from https://registry.yarnpkg.com/is-odd/-/is-odd-3.0.1.tgz in offline mode: snapshot not present in local store

12.21.0のstore addは、プロジェクトのロックファイルを読み、tarballのハッシュ値がintegrityと一致する項目に、そのtarballを結び付けます。12.20.0までは、tarballの中のpackage.jsonにある名前と版でしか結び付けなかったので、URLで記録された項目は探しても見つかりませんでした(#18000)。

tarballのURLやGitHubの依存がないプロジェクトなら、12.20.0でもこの手順でオフラインのinstallができます。それらの依存があるプロジェクトでは、12.21.0以降へ上げます。

12.20.0と12.21.0のどちらも既定の設定ではロックファイルの確認で止まる

前の節の比較は、minimumReleaseAgeを0にした結果です。設定を既定のままにすると、tarballを用意していても、12.20.0と12.21.0のどちらもinstallの途中で止まりました。

✗ Lockfile failed supply-chain policy check (4 entries in 1ms)
ERR_PNPM_NO_OFFLINE_META: Failed to resolve is-number in package mirror /root/.cache/pnpm/v12/metadata-full/https%3A+registry.npmjs.org/is-number.jsonl

pnpm 12のinstallは、ロックファイルの各項目にminimumReleaseAgeとtrustPolicyの決まりを当て直す確認をしてから進みます(pnpmの設定のドキュメント)。minimumReleaseAgeは、公開されてから決めた時間がたっていない版を入れない設定で、既定の値は1440分(1日)です。trustPolicyは、以前の版より信頼の度合いが下がった版を入れない設定で、既定は無効です。この確認にはレジストリーのパッケージの情報(公開の日時など)が要りますが、store addが用意するのはtarballだけです。そのため、ネットワークのない環境では確認が終わらずに止まります。

同じ症状の報告(issue #18063)に、開発チームは、オフラインのinstallに--trust-lockfileを付けるよう案内しています。--trust-lockfileはこの確認を飛ばすので、オフラインのinstallではminimumReleaseAgeの確認が行われません。確認を残すには、同じロックファイルを先にネットワークのある環境でpnpm install --frozen-lockfile --lockfile-onlyで確かめておく、というのが案内の内容です。

# ネットワークのある環境で、ロックファイルを確かめる
pnpm install --frozen-lockfile --lockfile-only

# ネットワークのない環境で、プロジェクトのフォルダーで実行する
pnpm store add ./tarballs
pnpm install --frozen-lockfile --offline --trust-lockfile

手元の12.21.0では、ネットワークのある環境での確認が「Lockfile passes supply-chain policies」で通り、ネットワークのない環境のinstallは既定の設定のまま3種類とも入りました。この手順は、ネットワークのある環境で確かめたロックファイルを、そのままオフラインの環境で使うことが前提です。ドキュメントは、外部の人がロックファイルを編集できるプロジェクトではtrustLockfileを使わないよう注意しています。

--trust-lockfile

ロックファイルの確認を飛ばす

12.21.0では、trustPolicy: no-downgradeにしたプロジェクトでも入りました。ドキュメントは、外部の人がロックファイルを編集できるプロジェクトでは使わないよう注意しています。

--config.minimum-release-age=0

trustPolicyが既定の無効のときだけ通る

12.21.0でtrustPolicy: no-downgradeにしたプロジェクトでは、同じエラーで止まりました。

pnpm store addはプロジェクトのフォルダーで実行する

12.21.0のstore addがtarballのURLやGitHubの依存に対応するのは、プロジェクトのロックファイルを読むときだけです。pnpmのドキュメントも、プロジェクトの外で実行すると、tarballはレジストリーの依存にしか使われないと説明しています。

手元で、プロジェクトの外(ルートのフォルダー)でstore addを実行してから、プロジェクトでinstallすると、12.21.0でもGitHubの依存で「snapshot not present in local store」と止まりました。プロジェクトの外から実行するときは、pnpm store add ./tarballs --dir プロジェクトのフォルダーのように--dirでプロジェクトを指定すると、3種類とも入りました。

オフラインのビルドで12.21.0以降を使うと、tarballのURLやGitHubの依存を、ストアの形式に合わせて自分で書き込む処理が要らなくなります。まずはネットワークのある環境でロックファイルを確かめ、プロジェクトのフォルダーでstore addと--trust-lockfileを付けたinstallを試して、すべての依存が入るかを確かめます。

参考資料

検証環境

  • macOS 27.2.1(Apple Silicon)、Docker Desktop 4.79.0
  • コンテナー: node:24-trixie(Node.js 24.22.3、git 2.47.3)、オフラインの検証はネットワークなし(--network none)
  • pnpm 12.20.0・12.21.0
  • 検証日: 2026年11月17日

この記事は、AIが調査と下書きを担当し、上記の環境で実際に動かして結果を確かめ、下書きとは別の担当が公開前に本文と出典を確認しています。制作と訂正の方針は編集・訂正方針で公開しています。