こんにちは！開発環境アーキテクトの先輩です。
今回は、Pythonのパッケージ管理における「ゲームチェンジャー」として世界中のエンジニアを熱狂させている`uv`について、実務で最も頭を悩ませるポイントの一つである「オンプレミス・閉域網（オフライン）環境での依存管理術」を徹底解説します。
「インターネットにつながっていないセキュアな本番環境や社内サーバーで、どうやってPythonライブラリをスマートにインストールするのか？」
この永遠の課題に対し、超高速パッケージマネージャーである`uv`を使って鮮やかに解決する方法を一緒に見ていきましょう。
これをマスターすれば、外部ネットが遮断された過酷な環境でも、まるで自宅の高速回線に繋いでいるかのように一瞬で依存関係を構築できるようになりますよ。毎日の開発やデプロイのストレスが劇的に消え去る感動を、ぜひ味わってください。
—
1. なぜ「uv」なのか？ 閉域網開発における圧倒的なアドバンテージ
これまでのPythonのパッケージ管理（`pip`や`poetry`など）を閉域網で使おうとすると、こんな苦労がありませんでしたか？
- 「依存関係の解決（リゾルブ）に数分〜数十分もかかり、挙句の果てにタイムアウトする」
- 「社内ミラーサーバー（DevpiやNexusなど）を立てたはいいが、ローカルキャッシュの同期がうまくいかない」
ここで登場するのが、Rust製超高速パッケージマネージャーである`uv`です。
`uv`が閉域網の救世主となる理由は、単にインストールが速いからだけではありません。「ローカルのインデックスやディレクトリを完全に掌握し、極限まで無駄なネットワーク往復を排除する設計」になっているからです。
内部で何が起きているかというと、`uv`は並行処理と強力なキャッシュ機構を駆使し、必要なホイール（`.whl`）ファイルを一網打尽でフェッチします。これを閉域網向けの「カスタムインデックス（ミラーサーバー）」や「ローカルディレクトリ」と組み合わせることで、完全オフライン環境であっても、現代的でモダンなPython開発環境をノータイムで再現できるようになるのです。
—
2. 閉域網運用の全体像とアーキテクチャ
オンプレミス環境で`uv`を運用する場合、大まかに以下の2つのアプローチが存在します。
1. 社内PyPIミラーサーバー方式：社内に `Devpi` や `Nexus` などのプロキシ・ミラーサーバーを立て、`uv`からそこを参照させる。
2. ローカルディレクトリ（ホイールバンドル）方式：インターネット接続環境で必要なパッケージをあらかじめ `.whl` として固めて持ち込み、ローカルディレクトリをインデックス代わりに使う。
今回は、より多くの現場で即座に効果を発揮する「カスタムインデックス（ミラーサーバー）の指定と、オフライン環境でのプロジェクト構築手順」に焦点を当てて解説します。
—
3. ステップ1：インターネット接続環境での準備（アセットの収集）
まずは、インターネットに接続できるマシン（またはセキュアな環境にデータを持ち込む前のビルドマシン）で、必要なパッケージのホイールを集めます。
今回は例として、Webフレームワークの `FastAPI` と軽量ASGIサーバーの `Uvicorn` を管理するプロジェクトを想定しましょう。
プロジェクトの初期化
インターネット接続環境で、`uv`を使ってプロジェクトを新規作成します。
新しいプロジェクトの作成
uv init uv-offline-demo
cd uv-offline-demo
依存関係として fastapi と uvicorn を追加
uv add fastapi uvicorn
このコマンドを実行すると、プロジェクトのルートに `pyproject.toml` と `uv.lock` が生成されます。`uv.lock` には、依存するすべてのパッケージの正確なバージョンとハッシュ値が記録されています。これがオフライン環境での「羅針盤」となります。
—
4. ステップ2：社内ミラーサーバー（またはローカルリポジトリ）の構築
閉域網のクライアントからアクセスできる場所に、PyPI互換のミラーサーバー（例: `Devpi`, `Sonatype Nexus`, `Bandersnatch` など）が稼働している前提で進めます。
もし簡易的にローカルフォルダーだけで完結させたい場合は、`uv export` や `uv pip compile` を使ってホイールをローカルにダウンロードすることも可能です。しかし、エンタープライズ環境では専用のミラーサーバーを立てるのが定石です。
社内ミラーサーバーのURLが仮に `https://pypi.internal.company.com/simple` であるとしましょう。
—
5. ステップ3：閉域網環境における uv の設定と構築
いよいよ舞台をインターネットから完全に遮断された閉域網環境（オフライン環境）に移します。
先ほどインターネット環境で作成したプロジェクトフォルダ（`pyproject.toml`, `uv.lock`）を、閉域網環境のサーバーへコピーします。
設定ファイルの配置（環境に合わせたインデックスの指定）
`uv`は、環境変数や設定ファイル（`uv.toml`）によって、パッケージの取得先（インデックス）を自由に変更できます。
プロジェクトのルートディレクトリに `uv.toml` を作成し、社内のミラーサーバーをプライマリインデックスとして強制します。
`uv.toml` の記述:
外部の公式PyPIへのフォールバックを完全に無効化し、社内ミラーのみを参照させる
[pip]
index-url = “https://pypi.internal.company.com/simple”
もし社内独自のプライベートリポジトリがある場合は、extra-index-urlも併用可能
extra-index-url = [“https://pypi.private.company.com/simple”]
> アーキテクトの知見：
> `uv`はデフォルトで公式PyPI（pypi.org）へのアクセスを試みます。閉域網環境でこれを放置すると、タイムアウトエラーが発生してデプロイが停止する原因になります。`uv.toml` または環境変数 `UV_INDEX_URL` で明確に向き先を固定することが、トラブルを防ぐ最大のコツです。
環境変数による指定（CI/CDパイプラインの場合）
もし設定ファイルを書きたくない、あるいはCI/CDのランタイム環境で動的に制御したい場合は、環境変数を使用します。
社内ミラーサーバーをデフォルトインデックスに指定
export UV_INDEX_URL=”https://pypi.internal.company.com/simple”
パブリックなPyPIへの自動フォールバックを禁止する（セキュリティおよびオフライン時の暴走防止）
export UV_PUBLISH_URL=”https://pypi.internal.company.com/simple”
—
6. ステップ4：オフライン環境でのプロジェクト同期（シンク）と動作確認
設定が完了したら、いよいよ閉域網環境で仮想環境を作成し、依存関係を同期（Sync）させます。
以下のコマンドを叩いてみてください。
1. Pythonの仮想環境を明示的に作成 (.venv ディレクトリが生成される)
uv venv
2. ロックファイルに基づき、社内ミラーから一瞬で依存関係をインストール
uv sync
実行ログのイメージ:
Using Python 3.11.2
Creating virtual environment at: .venv
Resolved 4 packages in 12ms
Prepared 4 packages in 45ms
Installed 4 packages in 85ms
+ annotated-types==0.6.0
+ fastapi==0.110.0
+ pydantic==2.6.4
+ uvicorn==0.28.0
信じられないほどのスピード（ミリ秒単位！）で、閉域網内のミラーサーバーから必要なパッケージが `.venv` に展開されたはずです。
精度高いHelloWorld的な動作確認
正しく依存関係が構築され、アプリケーションが動作するかを検証するためのスクリプトを作成しましょう。
`main.py` の作成:
from fastapi import FastAPI
FastAPIアプリケーションのインスタンス化
app = FastAPI()
@app.get(“/”)
def read_root():
“””
閉域網環境での動作確認用エンドポイント
“””
return {“message”: “Hello from Offline Environment with uv!”}
if __name__ == “__main__”:
import uvicorn
# ローカルホストのポート8000でサーバーを起動
uvicorn.run(app, host=”127.0.0.1″, port=8000)
これを実行してみます。
uv環境下でPythonスクリプトを実行
uv run python main.py
別ターミナル、またはブラウザ/curlからアクセスして確認します。
curl http://127.0.0.1:8000
出力結果: {“message”:”Hello from Offline Environment with uv!”}
見事に、外部ネットワークに一切アクセスすることなく、閉域網内で高速かつセキュアなPythonアプリケーションの実行環境が再現できました！
—
まとめ：今日の学びをあなたの現場へ
今回は、`uv`を用いたオンプレミス・閉域網環境でのミラーサーバー構築と依存管理術について解説しました。
- `uv.toml` や環境変数（`UV_INDEX_URL`）を適切に設定し、公式PyPIへの無駄なアクセスやタイムアウトを断ち切る。
- インターネット環境側で作成した `uv.lock` を持ち込み、閉域網内の社内ミラーから `uv sync` で一瞬にして環境を再現する。
- `uv run` を用いることで、仮想環境の有効化を意識することなくスマートにアプリケーションを実行する。
セキュリティが厳格な現場であっても、ツールの本質と設計思想を理解していれば、開発効率が落ちることはありません。むしろ、依存関係が完全にロックされた堅牢な環境を手に入れることができます。
これをマスターすれば、明日のデプロイや環境構築のイライラが嘘のように消え去るはずです。ぜひ、あなたのプロジェクトでも試してみてくださいね！