uvを用いてオフライン環境のWindowsでpythonを利用する

この記事では、インターネット接続がないオフライン環境において、uv と Embeddable package を用いてPython環境を構築・運用する手順の一例を紹介します。

uv は通常オンラインでの依存解決を前提としていますが、本記事では「オンライン環境で完結したプロジェクトを作成し、そのままオフラインへ持ち込む」方式を採用します。

この事例の特徴

• 実行方式: uv run を使用して実行する。
• uv の配置: PATH を通したプロジェクトフォルダ外（例: C:\bin）に配置する。
• Python の配置: プロジェクトフォルダ内に Python 本体（Embeddable package）を配置する。
• 運用フロー:
  1. オンラインPCでプロジェクトフォルダを作成する。
     • Pythonバージョン固定、ライブラリ固定。
     • 変更するには、プロジェクトフォルダをオンラインPCで作り直す必要あり。
  2. 作成したフォルダをオフラインPCに持ち込む。

補足:

• 本手順ではオフライン環境でのパッケージ追加は行いません
• 依存関係を変更する場合は、オンライン環境で再構築が必要です

---

1. uv をインストールする (共通)

1. uv のダウンロード
   uv の公式リリースページから、対象アーキテクチャの Windows 用ファイルをダウンロードする。
   (例: x64 Windows なら uv-x86_64-pc-windows-msvc.zip)
2. 整合性の確認
   Get-FileHash <ダウンロードしたファイルパス> を実行し、チェックサムが正しいか確認する。
3. 配置
   ファイルを解凍し、C:\bin などの任意のディレクトリに uv.exe を配置する。
4. 環境変数への追加
   ユーザー環境変数の PATH に C:\bin を追加する。
   下記の項目（2. Windows で PATH を追加する手順）を参考にする。
5. 確認
   PowerShell で uv --version を実行し、バージョンが表示されれば完了。

2. Windows で PATH を追加する手順 (共通)

1. Winキーを押し、「環境変数を編集」と入力して検索する。
2. 「ユーザー環境変数」の Path を選択して「編集」をクリック。
3. C:\bin を追加して OK で閉じる。
4. PowerShell / CMD / Windows Terminal を再配置（再起動）する。
5. $env:Path を実行し、追加したパスが含まれていることを確認する。

3. プロジェクトフォルダの作成 (オンラインPC)

C:\Projects\uv-trial をプロジェクトフォルダとします。

# 作業フォルダの作成
mkdir C:\Projects\uv-trial
cd C:\Projects\uv-trial

4. Python の取得 (オンラインPC)

1. Python 公式サイトにアクセスする。
2. Windows embeddable package (zip形式) をダウンロードする。
3. 例として、Python 3.13.13 の Windows embeddable package (64-bit) を選択。
4. 解凍して、プロジェクトフォルダ（C:\Projects\uv-trial）内に配置する。
   (例: C:\Projects\uv-trial\python-3.13.13-embed-amd64)

リンク例

• Python3.13.13
• Python3.14.5
• Python3.11.9

補足:

• Embeddable package は軽量ですが、pip や venv が標準では含まれません
• 本記事では uv によって環境管理を行うため、この制約を回避します

5. プロジェクトの初期化とパッケージ準備 (オンラインPC)

プロジェクトの初期化

# uv の初期化（指定した Python を使用）
uv init --bare --python python-3.13.13-embed-amd64

# 仮想環境の作成
uv venv --python python-3.13.13-embed-amd64

.venv/pyenv.cfg の修正（重要）

Embeddable package を利用する場合、絶対パスのままだと環境移動後に壊れるため、home パスを相対パスに修正します。
エディタで .venv/pyenv.cfg を開き、以下のように修正します。

home = python-3.13.13-embed-amd64

パッケージの追加

重要:

• --link-mode=copy を指定しない場合、キャッシュへのリンクになるためオフラインで壊れます
• このオプションにより、依存パッケージが .venv 内に完全コピーされます

# パッケージの追加例（パッケージは適宜調整してください）
uv add --link-mode=copy matplotlib numpy pandas

---

6. オフラインPCでの利用手順

オフラインPCでの事前準備

オンラインPCと同様に、下記の準備を行う

• uv のインストール
• PATH の設定

プロジェクトフォルダの持ち込みと確認

1. オンラインPCで作成した uv-trial フォルダを、オフラインPCへコピーする。
2. 動作確認: uv run python -c "import numpy; print(numpy.__version__)"
3. バージョン情報が出力されれば、成功です。

7. 運用上の注意

• パッケージ追加・更新はオンライン環境で実施する
• Pythonバージョン変更も同様に再構築が必要

8. 終わりに

uv と Embeddable package を組み合わせることで、比較的シンプルにオフラインPython環境を構築しました。