概要

• uv を使うことで、Pythonプロジェクトの 依存管理とビルド速度 が大幅に向上
• pyproject.toml で依存関係を管理し、 requirements.txt を廃止
• Docker環境 でのセットアップ手順とコマンド例を具体的に解説
• 非rootユーザー かつ venv未使用 の安全かつシンプルな構成
• uvコマンド による依存追加・更新・削除の運用方法

Docker環境でuvを使ったPython依存管理高速化

• uv を導入することで、従来のpipやvenvよりも 10倍以上のビルド速度向上 を体感
• venv（仮想環境）を使わず、 非rootユーザー （例: pythonユーザー）で運用
• pyproject.toml で依存関係を宣言し、 requirements.txt は不要
• uvのlockファイル （uv.lock）は依存ツリーを正確に反映、pip freezeよりも優れた管理
• Gitの差分 も最小限で移行可能、既存プロジェクトにも簡単に適用

pyproject.tomlとrequirements.txtの移行

• pyproject.toml にトップレベル依存関係を記述
• requirements.txt を削除し、 pyproject.toml と uv.lock のみで管理
• 例:
  • pyproject.toml
    • [project]
    • dependencies = [ "redis==5.2.1", ]
  • requirements.txt
    • redis==5.2.1（削除）

Dockerfileの変更ポイント

• uvバイナリ（uv, uvx） を公式リリースから取得し、 /usr/local/bin/ に配置
• pyproject.toml と uv.lock をプロジェクトルートにコピー
• 環境変数 設定
  • UV_COMPILE_BYTECODE=1: ビルド時にバイトコードを生成し、起動時の負荷軽減
  • UV_PROJECT_ENVIRONMENT="/home/python/.local": venvを作成せず、ローカルパスに直接インストール
• 依存インストールコマンド をbin/uv-install等のシェルスクリプトに分離し、Dockerfileから実行

uvによる依存インストールスクリプト例

• uv.lockがなければ自動生成、既存のlockファイルがあれば --frozen で厳密に再現
• --no-install-project でプロジェクト自体のパッケージ化をスキップ（必要に応じて削除可）
• 例:

  #!/usr/bin/env bash
  set -o errexit
  set -o pipefail
  if ! test -f uv.lock || ! uv lock --check 2>/dev/null; then
    uv lock
  fi
  uv sync --frozen --no-install-project
  

依存パッケージの追加・更新・削除運用

• ショートカットスクリプトで各種コマンドを簡単実行
  • ./run deps:install
    • 新しいイメージをビルドし、uv.lockをボリューム経由で更新
  • ./run deps:install --no-build
    • ビルド省略、uv.lockのみ更新
  • ./run uv [...]
    • 任意のuvコマンドを直接実行
• 依存追加例:
  • uv add mypackage --no-sync（pyproject.tomlとlockのみ更新、インストールなし）
  • その後 ./run deps:install で実際にインストール・反映
• 依存削除例:
  • uv remove mypackage --no-sync
• アップデート・バージョン指定も柔軟に対応
• ./run uv:outdated で依存のアップデート状況を一覧表示

運用のポイントとまとめ

• uv の sync コマンドで依存を厳密に再現、バージョンのズレを防止
• pyproject.toml と uv.lock のみで依存関係を一元管理
• Docker と組み合わせることで、 再現性・セキュリティ・高速化 を両立
• pip互換のサブコマンド も用意されているが、uv独自のワークフロー推奨
• 動画解説 や Git差分 も参考に、既存プロジェクトへの移行も容易

---

uv への移行や運用で困ったことがあれば、ぜひフィードバックを。 メール通知も低頻度でスパムなし、1クリックで解除可能。