uvを使ったPython環境構築-人工知能応用特論Ⅰ

2025年度 人工知能応用特論Ⅰ： 機械学習・データサイエンスのための プログラミング 第3回 Pythonの環境構築 東京農工大学大学院先進学際科学府 山田宏樹 1

スケジュール 第1回：Gitの基礎 第2回：Git・GitHubの実践 第3回：Pythonの環境構築 第4回：Visual Studio Code (VS Code) を活用した開発 第5回：読みやすいpythonコードの書き方 第6回：pytestを使ったテスト駆動開発 第7回：pytorch-lightningを使った深層学習の実装 第8回：機械学習のプロジェクトにおける実験管理 2

今回の授業の目標 再現可能なコードの実行環境の構築を学ぶ みなさんも経験ありませんか？公開されているコードや先輩から引き継いだコー ドの実行環境が全く再現できなかった経験が．今回の講義では，再現可能な環境 構築の方法を解説します． 3

実行環境 今回の講義で使うツールは以下の通り Docker Desktop Git Visual Studio Code (VS Code) 講義の課題で，上記のインストールは完了していると思います． 4

なぜ実行環境が再現ができなくなるのか ライブラリのバージョンの差異 使っているpythonライブラリのバージョンが違うと挙動が変わることがありま す．またものによっては後方互換を担保しないライブラリも多いです． ライブラリの依存関係による副作用 ライブラリには依存関係があり，その依存関係も再現しないと同じ結果を得るこ とが難しくなります． Python以外のツールの不整合 例えば，pytorchにはCUDAのバージョンに対応関係があり，その対応関係を満た したCUDAを使わないと正しく動作しないです． 5

どうやって解決する？ Python本体のバージョンやライブラリの依存関係の管理 → uv というツールで解決 Python以外のライブラリやツールの管理 → docker というツールで解決 本日の講義では uv と docker を中心に解説します． uv の解説に入る前に，pythonの仮想環境という概念を知る必要があります． 6

Pythonの仮想環境とは？ Pythonの仮想環境とは，プロジェクトごとにパッケージを管理することが可能な 枠組みのことです． なぜ仮想環境が必要？ 例えばこんなシチュエーションがありうる あるプロジェクトAでは，numpyのバージョン1.22を使用している．別のプロジェ クトBではバージョン2.2.6が必要であるが，システム全体のpythonにインストー ルするとバージョンの競合が発生してしまう．numpyはバージョン1.x系と2.x系で 仕様が異なるため，どちらかのバージョンに統一することはできない. python 3.3から venv による仮想環境機能が実装 により仮想環境を作れば，プロジェクトごとに独立したライブラリ構成を 構築でき，異なるバージョンのライブラリも共存させることができる． venv 7

venv による仮想環境の構築 仮想環境の構築 以下を実行すると， .venv ディレクトリが作られ，仮想環境ができます． python -m venv .venv の部分は自分がつけたい仮想環境の名前に変更することが可能ですが，慣 習的に .venv と名前をつけることが多いです．例えばVS Codeでは自動 で .venv/bin/python をpythonインタプリタとして認識してくれますし，一般的 な .gitignore のテンプレートは .venv/ をgitの管理の除外対象としています． 仮想環境の .venv はgitで管理してはいけません．例え共有しても仮想環境は他人 の環境では動かないですし，容量が大きいので百害あって一利なしです． .venv 8

仮想環境にパッケージを追加する MacとLinuxの場合，以下を実行すれば仮想環境を有効化できる． source .venv/bin/activate Windowsの場合は以下を実行して，有効化できる． .venv\Scripts\activate 仮想環境がアクティベートされると，シェルプロンプトの前に(仮想環境名)が表示 されます． 仮想環境を有効化した状態で， pip install すれば，仮想環境にパッケージを追 加することができ，そのパッケージは .venv/lib/python(バージョン番号)/sitepackages に置かれます． 仮想環境のアクティベートを解除する時は，以下を実行します． deactivate 9

少し昔に主流だった環境構築方法 venv ＋ pyenv + pip を使った方法 ではpython本体のバージョンの切り替えはできないので， pyenv というツ ールも使ってPythonに複数バージョンを共存させて環境構築します．仮想環境で は pip でpythonパッケージを追加します． venv requirements.txt を使ってパッケージを管理する 仮想環境を有効化した上で，以下を実行して requirements.txt を作ることで， 仮想環境にインストールされているパッケージの情報を他者と共有できます． pip freeze > requirements.txt 共有された requirements.txt を使って，まとめてパッケージをインストールで きます． pip install -r requirements.txt 10

requirements.txt 再現性が不十分 による管理の問題点 あくまで requirements.txt はインストールされたパッケージのリスト 間接依存関係を管理できないので，環境の再現ができないこともある． つまり，同じ requirements.txt を使っても時期や環境によって異なる結果 になることがある． 手動管理が煩雑 パッケージの更新や削除を自分で編集する必要がある 依存関係の競合が起きた場合、自分で解決しなければならない 11

ここまで， venv + pyenv + pip の管理方法や requirements.txt を紹介してきましたが，基本使わなくて いいです． uv を使えば上述した方法の機能を全て代替でき， requirements.txt よりも洗練されたパッケージ管理が可能 です． 12

(補足) 色々なパッケージ管理ツールについて これまで， pip , conda , poetry , rye などさまざまなパッケージ管理ツールが 出てきていますが，現状のおすすめは uv です．Pythonのパッケージ管理ツール のベストプラクティスはしょっちゅう変わっているので， uv もまた時代遅れにな るかもしれません．また，最近 Pixi という conda の上位互換のようなパッケー ジ管理ツールも登場しています．現状だと，Pythonのパッケージ管理のみをした いなら uv , Python以外の依存関係も管理したいなら Pixi というのが妥当な選択 かと思われます． 重要：パッケージ管理ツールは絶対に混ぜて使わないこと Python初心者がpipやcondaを混ぜて使って環境がめちゃくちゃになっているをた くさんみてきました．同一プロジェクトで複数のパッケージ管理ツールを混ぜて 使うのはNGです．パッケージがどこで管理されているのかわからなくなります． 13

uvとは？ はAstral社が提供している，Rustで書かれた高速なpythonパッケージ管理ツー ルです． uvの公式サイト uv 特徴 だけで， pip , poetry , pyenv , virtualenv などのツールを代替可能 pipよりも10-100倍高速 プロジェクトごとに任意のバージョンのpythonを扱える universal lockfileによりプロジェクト管理 (pythonのパッケージ管理も含む) が 可能 PythonやRustが入ってなくても， curl 等を使ってインストール可能 uv 14

• https://docs.astral.sh/uv/

uv をインストールする 公式サイトを参考にして uv をインストールしましょう．どの方法でインストール してもらっても構いません． 公式: Installing uv uv uv のアップデート のアップデートは以下で実行できます． uv self update 以降の解説は uv のバージョンが 0.9.4 のときに作っていることに留意してくだ さい．頻繁にアップデートがあるので，細かいところが変更されると思います． 15

• https://docs.astral.sh/uv/getting-started/installation/

uv の使い方: プロジェクトを作る uv init によりプロジェクトフォルダが作ることができます． uv init my_project は任意のプロジェクト名です．既に作成したいプロジェクトの直下 にいる場合は uv init だけで作れます． uv公式:Creating projects my_project 作られるファイルなど (uv公式: Project structure) で作られるディレクトリには少なくとも以下が含まれます． .python-version : このプロジェクトで使うpythonのバージョンが記載され たファイル pyproject.toml : プロジェクトのビルドシステム，依存関係，メタデータを 一元管理するための設定ファイル この段階ではまだpythonの仮想環境のディレクトリ .venv は作られないです． 16 uv init

• https://docs.astral.sh/uv/concepts/projects/init/
• https://docs.astral.sh/uv/guides/projects/#project-structure

uv init 以下を実行 したときのディレクトリ構成 uv init my-project ディレクトリ構成を表示する cd my-project tree -a 実行結果（ただし， .git 配下のファイルは表示していない）: . ├── .git ├── .gitignore ├── .python-version ├── main.py ├── pyproject.toml └── README.md をすると git の初期化もされるようですが，環境に git が入っていな 17 い場合どういった挙動になるかは未確認です． uv init

uv init --package でsrcレイアウトのプロジェクトを作る 個人的には --package オプションでプロジェクトを作るのがおすすめです． 研究では自作のパッケージを開発しながら提案手法の実装を行うことが多いの で，srcレイアウトを採用した方が良いです． （参考：src レイアウト対フラットレイアウト） uv init --package my_project で作られるディレクトリ構成 . ├── .git ├── .gitignore ├── .python-version ├── pyproject.toml ├── README.md └── src └── my_project └── __init__.py このように src 以下に my_project という自作パッケージ用のディレクトリが作 られます．また， src/my_project は自動でeditable installされるため，プロジェ クトのどこからでも import my_project が通るようになります． 18

• https://packaging.python.org/ja/latest/discussions/src-layout-vs-flat-layout/

(補足) editable install されているかの確認 今回は uv init --package my_project で作られたプロジェクトで，numpyを uv add した後， uv pip list で my_project がeditable installされているか確認 します． uv では uv add か uv venv をした後で仮想環境が作られるので，とり あえずnumpyを uv add しました． uv add numpy uv pip list uv pip list は uv に追加されたpythonパッケージを一覧表示します． Package Version Editable project location ---------- ------- ---------------------------------my_project 0.1.0 /Users/yamada/codes/my_project numpy 2.3.4 の部分がプロジェクトのパスに相当します． これで， my_project がeditable installされていることが確認されました． 参考：Development Mode (a.k.a. “Editable Installs”) /Users/yamada/codes/my_project 19

• https://setuptools.pypa.io/en/latest/userguide/development_mode.html

uv uv の使い方: Pythonのインストール では好きなバージョンのPythonをインストールできます． uv python install 3.12 複数バージョンのpythonも以下のようにインストールできます． uv python install 3.11 3.12 uv公式: Installing Python 20

• https://docs.astral.sh/uv/guides/install-python/

プロジェクトで使うpythonのバージョンを固定する プロジェクトでpython 3.11を固定して使いたければ，以下のように実行します． uv python pin 3.11 固定されたバージョンは .python-version に記載されます．ただし， pyproject.toml で requires-python = ">=3.12" と記載されていたら，バージ ョン 3.12 未満のバージョンには固定できず，エラーが出ます．バージョン 3.11 を固定したければ， requires-python = ">=3.11" に変更しましょう． uv公式: uv python pin 21

• https://docs.astral.sh/uv/reference/cli/#uv-python-pin

uv の使い方: Pythonパッケージを追加する でPythonパッケージを追加することができます．以下でnumpyをインス トールします． uv add uv add numpy 次のようにしてバージョンを指定することもできます． uv add "numpy==2.3.4" 追加したパッケージは pyproject.toml の dependencies に追加されます dependencies = [ "numpy>=2.3.4", ] また， uv.lock が更新され全ての依存関係がまとめて記録されます． uv公式: Managing dependencies 22

• https://docs.astral.sh/uv/guides/projects/#managing-dependencies

(補足) uv add と uv pip install の違い ， uv pip install はどちらもパッケージを追加するコマンドですが， 以下の違いがあります． uv add は pyproject.toml に登録しつつパッケージを追加します． uv pip install は仮想環境にパッケージを追加するのみで， pyproject.toml に登録されません． pyproject.toml に登録されていないと，パッケージの依存関係の情報が追加さ れないので再現性が著しく下がります．再現性を重視するなら uv pip install は極力使うべきではないです． しかし， uv add で追加できないパッケージが uv pip install なら追加できる ということもあるので，例外的に使わざるを得ない場面もあると思います．その 時は README.md に uv pip install で追加したパッケージとバージョンを記載し ておきましょう．また後述する Docker を使っているなら Dockerfile 内でその パッケージをバージョンを固定して uv pip install するようにしておくことで ある程度再現性を担保することも可能です． 23 参考: What's the difference between uv pip install and uv add uv add

• https://github.com/astral-sh/uv/issues/9219

(補足) uv add に失敗した場合 はデフォルトでPython Package Index (PyPI) でホストされているパッケー ジをインストールします． uv add でうまくいかなかった場合，PyPIにそのパッケ ージが存在しないか，正しく登録されていない可能性があります．そのため， PyPI以外からインストールすればうまくインストールできることもあります． （ちなみにPyPIの読み方はパイピーアイ） 例えば，GitHubリポジトリから以下のようにインストールできます． uv add # Install over HTTP(S). uv add git+https://github.com/encode/httpx # Install over SSH. uv add git+ssh://[email protected]/encode/httpx GitHubのリポジトリ以外からもインストールする方法がありますが，詳しくは以 下の公式サイトを参照してください． uv公式: Dependency sources 24

• https://docs.astral.sh/uv/concepts/projects/dependencies/#project-dependencies

(補足) uv でPyTorchをインストールする場合 PyTorchのインストールする時には単純に uv add torch としてはいけません． PyTorchは専用のindexでホストされているので，indexを指定してインストールを する必要があります．詳しくは解説しませんが，以下公式サイトを参考にしてイ ンストールしましょう． uv公式: Using uv with PyTorch また，以下のサイトも参考になります．ただし uv のバージョンによって挙動が変 わると思うので，その点は注意していください． Pythonのプロジェクト管理ツール uv のv0.5.3までの便利な機能 - dependencies編 25

• https://docs.astral.sh/uv/guides/integration/pytorch/
• https://zenn.dev/turing_motors/articles/1435807a1b16d5

Pythonパッケージを削除する 例えば，プロジェクトからnumpyを削除をしたい場合は以下を実行します． uv remove numpy をするとパッケージは削除され，自動で pyproject.toml と uv.lock が更新されます． uv remove Pythonパッケージのバージョンを更新する 例えばnumpyのバージョンを更新したい場合は以下を実行します． uv lock --upgrade-package numpy この時も，自動で pyproject.toml と uv.lock が更新されます． 26

uv の使い方: スクリプトの実行 を使えば，仮想環境を有効化せずに特定のスクリプトを実行することが できます．例えば， main.py を実行する時は以下のようにします． uv run uv run main.py もちろん，仮想環境を有効化していたら，以下のように実行できます python main.py uv公式: Running scripts 27

• https://docs.astral.sh/uv/guides/scripts/

uv の使い方: プロジェクト環境の同期 と pyproject.toml を他者に共有して， uv sync を実行すれば，パッケ ージの依存関係を再現することができます． プロジェクトの直下で以下を実行すれば，自動で uv.lock と pyproject.toml に 記録されている環境が作られます． uv.lock uv sync 演習：以下のリポジトリをクローンして環境を同期しましょう クローンするリポジトリ https://github.com/koki-yamada-lab/uv_example このリポジトリを各自のPCにクローンして，プロジェクト直下で uv sync を実行 してください．ちゃんと自動で記録されているパッケージがインストールされる か確認してください． 28

• https://github.com/koki-yamada-lab/uv_example

演習の実行例 git clone https://github.com/koki-yamada-lab/uv_example.git cd uv_example uv sync 以下， uv sync の実行結果 Using CPython 3.12.10 Creating virtual environment at: .venv Resolved 13 packages in 3ms Installed 12 packages in 37ms + contourpy==1.3.3 + cycler==0.12.1 + fonttools==4.60.1 + kiwisolver==1.4.9 + matplotlib==3.10.7 + numpy==2.3.4 + packaging==25.0 + pillow==12.0.0 + pyparsing==3.2.5 + python-dateutil==2.9.0.post0 + scipy==1.16.2 + six==1.17.0 29

ここまでで， uv を使ってPythonパッケージを管理する方法を 解説しました． 以降は Docker を使ったPython以外のツールを管理する方法 を解説します． 30

Dockerとは？ コンテナ仮想化を用いてアプリケーションを開発・配置・実行するためのオープ ンプラットフォームです． コンテナとは？ コードとその全ての依存関係をパッケージ化した，軽量で独立した実行環境 Jupyter Lab, My SQLなど Docker: コンテナを管理 Linux, macOS, Windows 31

コンテナを使うメリット メリット 独立した実行環境：「アプリ+依存関係+設定」をまとめてコンテナに閉じ込 めることで，環境の違いによる問題を回避できる 再現性： Dockerfile に環境構築手順を書いておくことで，同じ開発環境を 再現可能．つまり，開発マシンが変わっても同じ動作を保証できる． 32

Dockerの用語 Dockerfile 「どんな環境を構築するか」を記述したスクリプトファイル．Docker imageの設 計図です． Docker Image Dockerfileから作られる実行可能な環境のテンプレート．Docker imageからDocker containerが作られます．Docker imageをカスタマイズして，新しくDocker image を作ることもできます． Docker container Docker imageをもとに作られる，実際に動く実行環境．Docker imageは不変です が，コンテナは実行時に変更が可能です．ただし，コンテナを削除すると変更内 容も消えます (volumeをマウントしていると変更を保存できる)． 33

VS Codeの機能: Dev Container Dockerを使うには，本来はCLIで docker run 等を実行し，コンテナを立ち上げた りする必要があります．しかし，VS Codeが提供しているDev Containerという機 能を使えば，プロジェクト専用のDocker開発環境を自動で立ち上げ，VS Codeか ら直接操作できるようになります． Dev Containerの詳しい使い方は次回講義に解説します． とりあえず，Dev Containerが正しく動くかの検証をしておきましょう．VS Code とDocker Desktopがインストールされていれば正しく動作するはずです． 34

演習: Dev Containerを起動してみる 1. 以下，演習用のリポジトリをクローンしてください． https://github.com/koki-yamada-lab/devcontainer_lecture 2. クローンしてきた devcontainer_lecture というプロジェクトをVS Code で 開いてください． 3. Dev Containerを使う準備をしましょう．(参考: Dev Containers tutorial) 4. VS Code 左下にある青い >< マークをクリックして Reopen in Container を クリックしてください．このときDocker Desktopは起動中でないといけませ ん． 5. Dev Container環境が起動し，VS Codeの左下が Dev Container: Lecture of Dev Container と表示されていたら，コンテナがうまく起動していること が確認できます． 35

• https://github.com/koki-yamada-lab/devcontainer_lecture
• https://code.visualstudio.com/docs/devcontainers/tutorial

演習の実行例 1. 演習用のリポジトリをクローン 下記リポジトリをクローンしましょう． https://github.com/koki-yamada-lab/devcontainer_lecture HTTPSで認証している場合 git clone https://github.com/koki-yamada-lab/devcontainer_lecture.git SSHで認証している場合 git clone [email protected]:koki-yamada-lab/devcontainer_lecture.git 36

• https://github.com/koki-yamada-lab/devcontainer_lecture

2. クローンしてきたプロジェクトをVS Codeで開く VS Code左上のEXPLOREで Open Folder をクリックし，クローンしてきたフォル ダを開きましょう．EXPLOREのところでプロジェクト名 DEVCONTAINER_LECTURE が以下のように表示されていることを確認します． 37

3. Dev Containerを使う準備 以下サイトInstall DockerとInstall the extensionの作業を完了しておく必要がありま す．(参考: Dev Containers tutorial) みなさんはDocker Desktopをインストール済みだと思うので，Docker Desktopが起動しているか確認をまずしてください． VS Codeの拡張機能 Dev Containers をインストールしてください．上記サイ トで Install the Dev Container extension のボタンを押すと Dev Containers のインストール画面が出ます． 38

• https://code.visualstudio.com/docs/devcontainers/tutorial

4. Dev Containerを起動する VS Code 左下にある青い >< マークをクリックして表示されるところから Reopen in Container をクリックしてください． Reopen in Container が表示 されない人は以下を確認してください． EXPLOREでプロジェクト直下に .devcontainer があるかを確認する Docker Desktopが起動中か確認する VS Codeの拡張機能 Dev Containers がインストールされているか確認する コンテナが起動するまで，少し時間がかかります（たぶん1-3分程度）． コンテナの起動に失敗した場合は，ログを見て各自で対応しましょう． 2025年10月22日時点では動作することが確認できているので， Dockerfile や devcontainer.json には問題ないはずです． 39

5. コンテナが起動していることを確認する Dev Container環境が起動し，VS Codeの左下が Dev Container: Lecture of Dev Container と表示されていたら，コンテナがうまく起動していることが確認 できます．VS CodeのTERMINALの Dev Containers が以下のように止まっている ように見えますが，問題ありません． Dev Containers のターミナルは閉じてし まって構いません． 40

参考になる資料 Pythonの「仮想環境」を完全に理解しよう Pythonの仮想環境がどう動いているのかなど詳しく説明されています． 深層学習を用いた実験における再現可能な環境構築 「Pythonで学ぶ画像生成」という本の著者の北田さんが書いている再現可能 な環境構築の記事です．この記事以外にもPythonのプログラミングに役立つ 記事を書かれているので，一度読むことをおすすめします． CyberAgent AI Lab研修 / Container for Research CyberAgent AI Lab研修資料のコンテナやDockerに関するスライド資料です． CyberAgent AI Labは研究に役立つ研修資料を公開しているので，一度読んで みることをおすすめします． 41

• https://speakerdeck.com/os1ma/pythonno-jia-xiang-huan-jing-wowan-quan-nili-jie-siyou
• https://note.com/shunk031/n/n0f0e9e42b5aa?magazine_key=m84877e9f9649
• https://book.impress.co.jp/books/1123101104
• https://note.com/py_img_gen/m/m84877e9f9649
• https://speakerdeck.com/chck/container-for-research
• https://cyberagent.ai/blog/research/20228/

課題 課題内容 自分のPCにGitHub CLIをインストールし， gh auth login による認証が成功して いる画面のスクリーンショットをSiriusで提出してください．ファイル名は 学籍番 号_名前_github_cli としてください．スクリーンショットの形式は png , jpeg , pdf のどれかにしてください 注意事項 ファイル名が正しいか確認すること． 締め切り 日本標準時で次回講義の前日の23:59まで 42

• https://github.com/cli/cli#installation

GitHub CLIによる gh auth login の実行結果 gh auth login 実行結果： ? Where do you use GitHub? GitHub.com ? What is your preferred protocol for Git operations on this host? HTTPS ? Authenticate Git with your GitHub credentials? Yes ? How would you like to authenticate GitHub CLI? Login with a web browser ! First copy your one-time code: [ここにワンタイムパスワードが出ます] Press Enter to open https://github.com/login/device in your browser... ✓ Authentication complete. - gh config set -h github.com git_protocol https ✓ Configured git protocol ✓ Logged in as [ここにGitHubアカウントのidが出ます] ! You were already logged in to this account 43

ここまで資料をご覧になっていただきありがとうございます. 資料に間違いがあったり，より良いベストプラクティスがある 場合はご連絡ください．次回以降の講義にフィードバックを活 かします． Twitter: @KokiYamada6 本講義は，学習コストと得られる恩恵のバランスをとっています．より良いベス トプラクティスがあったとしても，学習コストの理由により採用しない場合があ ります．その点についてご了承ください． 44

• https://x.com/KokiYamada6