【備忘録】Pythonの超高速パッケージマネージャー「uv」の導入からプロジェクト立ち上げ・実行までの基本フロー

uv 導入備忘録

Pythonプロジェクトの立ち上げから実行までの基本フロー (Rye後継)

💡 uvとは？ Ryeと同じAstral社が開発する、Rust製の超高速Pythonパッケージ＆プロジェクトマネージャーです。現在、新規プロジェクトではRyeよりもuvの使用が公式に推奨されています。

お使いのOSに合わせてuvをインストールします。

ターミナルで以下のコマンドを実行します。

curl -LsSf https://astral.sh/uv/install.sh | sh

PowerShellを開いて以下のコマンドを実行します。

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

⚠️ 注意
インストール後はパスを反映させるため、一度ターミナルを再起動してください。

新しいプロジェクト用のディレクトリを作成し、初期化します。

# my-project は任意のプロジェクト名に変更してください uv init my-project cd my-project

作成された pyproject.toml を開き、[project] セクションにライセンス情報を追記します。

[project] name = "my-project" version = "0.1.0" license = { text = "MIT" } # この行を追記

※合わせて、プロジェクト直下に LICENSE という名前でMITライセンスの雛形ファイルを作成・配置しておきます。

プロジェクトで使用するPythonのバージョンを固定（Pin）します。システム側のPythonバージョンに依存せず、uvが必要なバージョンを自動で取得します。

# 例: Python 3.12 を指定する場合 (.python-versionファイルが生成されます) uv python pin 3.12

プロジェクトに必要な外部ライブラリを追加します。pyproject.toml への要件追記が行われます。

uv add requests

uv add --dev pytest

パッケージを瞬時にダウンロードし、プロジェクト専用の仮想環境（.venv）を構築します。環境の再現性を担保する uv.lock ファイルが生成・更新されます。

uv sync

💡 補足
uvでは uv add コマンドを実行した時点で自動的に同期（インストール）も行われるため、手動編集をした場合などに明示的に uv sync を実行します。

仮想環境を手動でアクティベートしなくても、uv run 経由で安全かつ高速にスクリプトやツールを実行できます。

uv run python hello.py

# 例: pytestを実行する場合 uv run pytest

Ryeとuvはどちらも標準的な pyproject.toml に対応しているため、移行は非常に簡単です。以下の手順でシームレスにuv環境へ切り替えることができます。

不要なファイルの削除（クリーンアップ）
Ryeが生成した古い仮想環境とロックファイルを削除します。
# Mac/Linuxの場合 rm -rf .venv requirements.lock requirements-dev.lock
uvで環境を再構築・同期
既存の pyproject.toml の依存関係を自動で読み取り、新しい環境を構築します。
uv sync
実行確認
エラーが出なければ移行完了です！今後は uv run や uv add でプロジェクトを管理します。