venvからPythonパッケージ管理ツールuvへの移行方法
uvとは
uv は Rust で記述された、Python 向けの超高速パッケージマネージャーです。
仮想環境構築、依存関係解消、Python本体のバージョン管理も可能です。
解決できること
- インストールが超高速（Pytorchや関連パッケージなどのインストールには便利）
- git & GitHub との相性が◎ （
.venvを除外し、pyproject.tomlとuv.lockによる環境再現が可能） - チームで同一環境を再現しながら一つのプロジェクトを使用できる
バージョン
- Ubuntu 22.04
- Python 3.12.3
uvインストール方法
uv インストールはcurlを使用して行います。
curlをインストールしていない場合はインストールします。
curl -LsSf https://astral.sh/uv/install.sh | sh
pathを反映
source ~/.bashrc
バージョン確認
uv --version
プロジェクトフォルダでuv初期化
# 例
mkdir your_project
cd your_project/
uv init
pyproject.tomlとuv.lockが作られます。
your_project/
├─ pyproject.toml ←（依存関係の宣言ファイル）
├─ uv.lock ←（依存関係のロックファイル）
もしくは、以下のようにinitの後ろに、ディレクトリを指定することで、プロジェクトディレクトリ直下を汚すことなく、uv関連ファイルをサブディレクトリにまとめることができます。
./your_project/.uv下にuv関連ファイル作成
# 例
cd your_project/
uv init .uv
※ ただし、VSCode の Python インタープリター自動検出とは相性が悪いため、
VSCode を使用する場合は プロジェクト直下で uv init する方が無難 です。
uvにPython バージョン固定
.python-versionファイルが作成され、ファイルにpythonバージョン指定情報が記述されます。
uv python pin 3.12
requirements.txtからの移行（!!!重要!!!）
requirements.txtが存在する場合は、以下のようにすべてのrequirements.txt内に記載されているパッケージをインストールできます。
以下のコマンドで 依存関係を pyproject.toml に変換しつつ追加 できます。
uv add -r requirements.txt
補足 : requirements.txt作成方法
既存のプロジェクト内の環境(pythonパッケージ一覧)をrequirements.txtに記述します。
pip freeze > requirements.txt
仮想環境を使用した実行
uv run main.py
uvでパッケージのインストール
# パッケージ追加
uv add <package_name>
# まとめて
uv add numpy pandas matplotlib
uvでパッケージのアンインストール
uv remove <package_name>
VSCodeでPythonインタープリター指定
uvではVScodeのpython拡張に対してインタープリタを自動登録してくれないので、手動で指定する必要あり。
VScodeのpythonインタープリタと仮想環境は独立しているとのことなので、uv run main.pyなどで、python実行はできるが、プロジェクト用のインタープリタが起動してくれないので、おそらく不便なはずです。
解決方法
uvでvenvを作成
結局venvを作成しないとVS codeでは読み取ってくれないみたいです。
gitを使用する場合は.gitignoreに.venv/が記述されているか確認。
.venvディレクトリが作成されます。
uv venv
ctrl + shift + Pで、setting.jsonを開き、以下のように指定する
※以下、python3.12の部分は各自で使用するものを指定してください。
.vscode/settings.json
{
"python.defaultInterpreterPath": ".venv/bin/python3.12"
}
それでもVScodeのインタープリタが起動しない場合
以下を試す
- VScode再起動
- python拡張機能が有効か確認後再起動
- venvが作成されているか確認
- setting.json内のpathの記述が自分の環境内で正しいか確認
私は4つ目が誤っていました。
補足：uvにおける仮想環境の考え方
uv では、仮想環境は「activate するもの」ではなく、
uv run などのコマンド実行時に自動的に使用される設計になっています。
そのため、VSCode の Python インタープリターとは概念的に独立しています。
まとめ
uv は、pip を用いた場合と比べてパッケージのインストール速度が非常に高速であり、
特に PyTorch などの容量が大きいパッケージを導入する際のストレスを大きく軽減できます。
また、pyproject.toml と uv.lock を用いた依存関係管理により、チームで同一の開発環境を再現しやすい点も大きなメリットです。
VSCode との連携については、Python インタープリターの登録を手動で行う必要があり、
初見ではやや手間に感じる部分もありました。
しかし、uv における仮想環境の考え方や VSCode 側の仕組みを理解すれば、
運用自体は決して難しいものではなく、十分に実用的だと感じました。