uv で作った環境を、インターネットにつながっていない PC でも再現したい場面があります。
たとえば、こんなときです。
- 社内ネットワークの制限で、対象PCは外部インターネットに出られない
- 検証用PCをオフラインで使いたい
- 配布先PCでは、事前に必要なものだけ持ち込みたい
この記事では、uv で作った環境をオフラインPCで再現する考え方を書きます。
先に結論
方法はあります。
ただし、「オフラインPCがゼロの状態でも、何も準備せずに再現できる」という意味ではありません。
uv の公式な考え方としては、オンラインPCで必要な Python と依存関係を先に取得し、オフラインPCではローカルに持ち込んだデータだけを使って --offline 実行する、という形になります。
つまり、ポイントは次の3つです。
-
pyproject.tomlとuv.lockを持っていく -
uvのキャッシュを持っていく - 必要なら
uv管理の Python 本体も持っていく
この方法が向いているケース
- オンラインPCとオフラインPCが同じ Windows 環境
- CPU アーキテクチャが同じ
- Python の要求バージョンが同じ
-
uvのバージョンもできるだけそろっている -
uv.lockがあり、依存が固定されている
この条件がそろっているほど、再現しやすいです。
逆に難しくなりやすいケース
- OS やアーキテクチャが違う
-
uv.lockがなく、依存関係が未固定 - Git URL や外部URL依存がある
- ビルドに別のネイティブツールが必要
このあたりが入ると、「Python パッケージを持っていけば終わり」にならないことがあります。
基本の考え方
オフラインPCではネットワークに出られないので、uv はローカルにあるものしか使えません。
公式CLIでも、--offline は「ネットワークアクセスを無効化し、ローカルキャッシュとローカルファイルだけを使う」と説明されています。
そのため、オンラインPCで先に次を準備しておきます。
- プロジェクトファイル
- 依存パッケージのキャッシュ
- 必要な Python 本体
-
uv自体
まずはオンラインPCで準備する
ここでは、すでにプロジェクトがオンラインPCで動いている前提で進めます。
1. uv.lock を含めてプロジェクトをそろえる
まず、プロジェクトで次を実行して、ロックファイル基準で環境をそろえます。
uv sync --frozen
uv.lock がある状態で --frozen を使うと、ロックファイルを更新せずに、その内容でそろえられます。
2. キャッシュを整理する
uv sync --frozen を実行すると、過去にインストールしたパッケージのキャッシュも残ったままになっています。
次を実行すると、現在のプロジェクトから参照されていない古いキャッシュだけを削除できます。
uv cache prune
これにより、「今のプロジェクトに必要なものだけ残ったキャッシュ」になり、オフラインPCへ持ち込むデータを小さくできます。
3. キャッシュの場所を確認する
次で、uv のキャッシュ場所を確認できます。
uv cache dir
このキャッシュに、ダウンロード済みの依存パッケージが入ります。
4. uv 管理Pythonの場所を確認する
uv 管理の Python を使っているなら、次で場所を確認できます。
uv python dir
ここに、uv が管理している Python 本体が入っています。
uv 管理Pythonではない場合
もし Python を uv 管理ではなく、公式インストーラーなどで入れているなら、その Python 本体は別途オフラインPCへ用意する必要があります。
この場合、uv のキャッシュだけ持っていっても、同じ Python が無ければ再現できません。
何をオフラインPCへ持っていくのか
最低限、次を持っていきます。
- プロジェクトフォルダ
-
uvのキャッシュディレクトリ -
uv管理の Python ディレクトリ - 同じバージョンの
uv.exe
オフラインPCでのフォルダ構成
持ち込んだデータは、オフラインPCの次の場所に置きます。
C:\Users\<ユーザー名>\
├── .local\
│ └── bin\
│ └── uv.exe ← uv.exe を配置（PATH に追加）
└── Documents\
├── uv-offline\
│ ├── cache\ ← uv キャッシュをコピー
│ └── python\ ← uv 管理の Python をコピー
└── <プロジェクト名>\ ← プロジェクトフォルダをコピー
├── pyproject.toml
├── uv.lock
└── （ソースコード等）
<ユーザー名> と <プロジェクト名> は自分の環境に合わせて読み替えてください。
プロジェクトフォルダで大事なもの
pyproject.tomluv.lock- ソースコード
.venv は持っていくべきか
自分は、.venv はそのまま移すより、オフラインPCで作り直す方が分かりやすいと思います。
仮想環境は絶対パスや環境差分を含みやすいので、「そのままコピーして終わり」より、「uv sync で作り直す」方が安全です。
オフラインPCに uv をセットアップする
uv.exe をコピーしただけでは、まだ uv コマンドとして使えません。
Windows は「どのフォルダにある .exe を実行すればよいか」を知らないので、場所を教える設定（PATH）が必要です。
なお、C:\Users\<ユーザー名>\.local\bin は Windows のデフォルトではPATHが通っていません。
uv を公式インストーラーで入れると自動で設定されますが、オフラインPCでは手動コピーのため、自分で設定する必要があります。
1. フォルダを作って uv.exe を置く
エクスプローラーでフォルダを作ります。
- エクスプローラーを開く
- アドレスバーに
%USERPROFILE%と入力して Enter を押す
（C:\Users\<自分のユーザー名>のフォルダが開きます） - 何もない場所で右クリック → 「新規作成」→「フォルダー」
- フォルダ名を
.localにする（先頭にドット.があることに注意） - 作った
.localフォルダを開いて、同じ手順でbinフォルダを作る - 持ち込んだ
uv.exeを、このbinフォルダにコピーする
2. PATH を通す
-
Win + Sを押し、「環境変数」と検索する - 「システム環境変数の編集」をクリックして開く
- 画面下の「環境変数」ボタンをクリックする
- 上段「ユーザー環境変数」の一覧から
Pathを選んで「編集」をクリックする - 右上の「新規」をクリックし、次のパスを入力する
C:\Users\<ユーザー名>\.local\bin
- 「OK」→「OK」→「OK」で画面を閉じる
3. ターミナルを再起動して確認する
PATH の設定は、ターミナルを開き直さないと反映されません。
一度閉じて開き直してから、次のコマンドを実行します。
uv --version
バージョン番号が表示されれば、設定は完了です。
キャッシュと Python をオフラインPCに配置する
「オフラインPCでのフォルダ構成」に沿って、エクスプローラーでフォルダを作りデータをコピーします。
1. フォルダを作る
- エクスプローラーを開き、左側の「ドキュメント」を開く
- 何もない場所で右クリック → 「新規作成」→「フォルダー」
- フォルダ名を
uv-offlineにする -
uv-offlineを開いて、同じ手順でcacheフォルダとpythonフォルダを作る
2. データをコピーする
オンラインPCから持ち込んだデータを、次の対応でコピーします。
| オンラインPCの内容 | オフラインPCの保存先 |
|---|---|
uv cache dir で確認したフォルダの中身
|
Documents\uv-offline\cache\ の中 |
uv python dir で確認したフォルダの中身
|
Documents\uv-offline\python\ の中 |
| プロジェクトフォルダ | Documents\<プロジェクト名>\ |
フォルダごとではなく、キャッシュとPythonは中身をコピーする点に注意してください。
オフラインPC側での流れ
オフラインPCでは、持ち込んだキャッシュとPythonを使って環境を再現します。
基本形は次です。
uv sync --offline --frozen --no-python-downloads
それぞれの意味
-
--offline: ネットワークアクセスをしない -
--frozen:uv.lockを更新しない -
--no-python-downloads: Python をダウンロードしようとしない
つまり、「ローカルに持ち込んだものだけで、ロック済み環境を再現する」という考え方です。
キャッシュやPythonの場所が違う場合
オンラインPCとオフラインPCで保存場所が違うなら、uv にその場所を教える必要があります。
コマンドプロンプトの場合
set UV_CACHE_DIR=C:\Users\<ユーザー名>\Documents\uv-offline\cache
set UV_PYTHON_INSTALL_DIR=C:\Users\<ユーザー名>\Documents\uv-offline\python
uv sync --offline --frozen --no-python-downloads
PowerShell の場合
$env:UV_CACHE_DIR = "C:\Users\<ユーザー名>\Documents\uv-offline\cache"
$env:UV_PYTHON_INSTALL_DIR = "C:\Users\<ユーザー名>\Documents\uv-offline\python"
uv sync --offline --frozen --no-python-downloads
<ユーザー名> は自分のユーザー名に置き換えてください。
ここは、環境変数の書き方だけがシェルごとに違います。
uv sync 自体のコマンドは同じです。
うまくいきやすい手順
初心者向けには、次の順番がおすすめです。
- オンラインPCで
uv sync --frozen -
uv cache pruneでキャッシュを整理する -
uv cache dirとuv python dirでそれぞれの場所を確認する - プロジェクトフォルダ、キャッシュ、Python本体、
uv.exeをUSB等にコピーする - オフラインPCでフォルダ構成に沿って配置する
- キャッシュ →
Documents\uv-offline\cache\ - Python →
Documents\uv-offline\python\ - プロジェクト →
Documents\<プロジェクト名>\ -
uv.exe→.local\bin\
- キャッシュ →
-
uv.exeのPATHを通す - プロジェクトフォルダでターミナルを開き、環境変数を設定して
uv sync --offline --frozen --no-python-downloadsを実行する -
uv run python --versionで確認する
どこで失敗しやすいか
uv.lock がない
完全な再現がしにくくなります。
オフライン再現をやりたいなら、uv.lock はかなり大事です。
Python 本体を持っていっていない
--no-python-downloads を付けると、必要な Python が見つからない時点で止まります。
これは失敗ではなく、「事前準備不足が分かる」のでむしろ安全です。
依存に URL や Git がある
ローカルに必要データがなければ、オフラインでは取得できません。
この場合は追加準備が必要です。
自分ならどう運用するか
自分なら、オフライン再現を考えるプロジェクトでは、次をセットで管理します。
pyproject.tomluv.lock- 使用する Python minor 系
- オフライン用に準備したキャッシュ一式
ここまでそろえておくと、「どのPCでも近い状態を作る」という意味でかなり強くなります。
まとめ
今回のポイントは次のとおりです。
-
uvでもオフラインPCでの再現は可能 - 前提は「オンラインPCで必要データを先に取っておく」こと
-
uv sync --offline --frozen --no-python-downloadsが基本形 -
uv.lock、キャッシュ、Python 本体が重要 -
.venvを丸ごと移すより、オフラインPCで再作成する方が安全
完全に何もないオフラインPCで一発再現、というよりは、「持ち込んだ材料だけで再現する」方法だと考えると分かりやすいです。
参考
- uv CLI reference: https://docs.astral.sh/uv/reference/cli/
- uv Locking and syncing: https://docs.astral.sh/uv/concepts/projects/sync/
- uv Caching: https://docs.astral.sh/uv/concepts/cache/
- uv Storage: https://docs.astral.sh/uv/reference/storage/
- uv Settings: https://docs.astral.sh/uv/reference/settings/
補足
この記事は生成AIを活用して作成しました。