uv入門

winding road photography
2025.09.09

「pip と venv を毎回作って管理するのめんどくさいなあ」と思っている方にぜひ読んでもらいたい内容です。さらにおまけとして「PyTorch の GPU 版を uv で入れる方法」も最後に記載しております。

uvとは

uv は Rust 製の新しい Python 環境・パッケージ管理ツールです。
特徴はざっくりいうとこんな感じ。

  • 速い！ pip よりも 10〜100 倍高速といわれてます
  • 全部入り！ pip, venv, pip-tools, poetry, pyenv の機能をまとめてカバー
  • プロジェクトごとに.venvが自動で作られる → 依存関係が混ざらない
  • Windows / macOS / Linux どこでも動く

インストール方法 (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

終わったら:

uv --version

で確認できます。
PATH に通らない場合は C:\Users\<ユーザー名>\.local\bin を追加してあげましょう。

プロジェクト初期化と Python バージョン指定

uv init myproject
cd myproject

構成例:

myproject/
├── .python-version
├── pyproject.toml
├── main.py
└── README.md

初期化時に Python バージョン指定も可能です：

uv init myproject --python 3.11

あとから固定するなら：

uv python pin 3.11

.venv 仮想環境とパッケージ管理

例: requests を入れる

uv add requests

→ .venv が作られ、依存関係は pyproject.toml に追記。

削除したいときは：

uv remove requests

その他よく使うコマンド：

uv venv                 # 仮想環境作成
uv add --dev pytest     # 開発用依存を追加
uv tree                 # 依存ツリー表示

ロックファイルと環境再現

uv lock
uv sync

これで uv.lock にバージョンが固定され、別の環境でも同じ環境を .venv に再現できます。
CI やチーム開発でとても便利。

ロックファイルを共有するときの注意

ここ、大事なので別枠で。

  • 必要なのは pyproject.toml と uv.lock の両方
    • pyproject.toml → プロジェクトの依存宣言
    • uv.lock → 具体的なバージョン固定
  • どちらも git にコミットしておけば、別のマシンでも
git clone <project>
cd <project>
uv sync

で同じ環境が再現できます。

既存プロジェクトに uv を導入する場合

既にあるプロジェクトでも安心。
そのディレクトリで：

uv init

とすれば OK。

  • 既存の requirements.txt や pyproject.toml があれば取り込む
  • なければ新しく pyproject.toml を生成

あとは uv add で必要なパッケージを追加していけば、uv 管理プロジェクトに早変わりです。

uv run で仮想環境を意識しない実行

uv run python main.py
uv run pytest

仮想環境の activate は不要。

おまけ：PyTorch GPU 版を入れる方法

pyproject.toml に専用 index を追加します：

[[tool.uv.index]]
name = "pytorch-cu118"
url = "https://download.pytorch.org/whl/cu118"
explicit = true

[tool.uv.sources]
torch = [
  { index = "pytorch-cu118", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }
]
torchvision = [
  { index = "pytorch-cu118", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }
]

その上で：

uv add torch torchvision

→ Windows/Linuxなら GPU ビルドが入ります。

pip / poetry との比較 (ざっくり)

  • pip + venv → シンプルだが分散管理
  • poetry → 機能多いが重め
  • uv → 速い・シンプル・全部入り

まとめ

おまけで PyTorch GPU 版も導入可能

プロジェクトごとに .venv が作られ依存を分離

uv lock + uv sync で環境再現

pyproject.toml と uv.lock を一緒に共有するのが大事

既存プロジェクトでも uv init で簡単に移行できる

コメント