こんにちは、JS2IIUです。
Python開発において、パッケージ管理・仮想環境管理・依存関係の整理は避けて通れない重要なステップです。従来は pip、virtualenv、pipx、pyenv、poetry など複数のツールを組み合わせて対応していましたが、設定の煩雑さや処理速度の遅さに悩んだ方も多いのではないでしょうか。
そこで登場したのが「uv」です。Rustで書かれたこの新しいツールは、pipの10倍以上の速さを実現し、複数のツールの役割を1つに統合することで、高速かつシンプルなPython開発環境の構築を可能にします。
本記事では、uvを使ってプロジェクトを初期構成する方法を、実際のファイル構成とコマンド例を交えて丁寧に解説します。まずは本記事の手順に従ってお試しして、徐々に慣れていきましょう。今回もよろしくお願いします。
uvのインストール
まずは、uv本体のインストールから始めましょう。以下の方法で簡単にインストールできます。
推奨インストール方法（Unix/macOS/Windows）
ターミナルで以下のコマンドを実行します。
pip install uvバージョンを確認しておきます。
uv --versionなおuvの公式ページには他にも様々なインストール方法が紹介されています。お使いの環境に適した方法でインストールしてください。
Installation | uv
uvのコマンド
インストールできたら、次のコマンドを実行してみます。ヘルプが表示されます。ヘルプの一部を抜粋します。
uvCommands:
run Run a command or script
init Create a new project
add Add dependencies to the project
remove Remove dependencies from the project
sync Update the project's environment
lock Update the project's lockfile
export Export the project's lockfile to an alternate format
tree Display the project's dependency tree
tool Run and install commands provided by Python packages
python Manage Python versions and installations
pip Manage Python packages with a pip-compatible interface
venv Create a virtual environment
build Build Python packages into source distributions and wheels
publish Upload distributions to an index
cache Manage uv's cache
self Manage the uv executable
version Display uv's version
help Display documentation for a commandプロジェクトの初期化テンプレート
ここでは、uvを使って実際にプロジェクトを立ち上げる際のディレクトリ構成と初期設定の流れを紹介します。
ディレクトリ構成（例）
以下のような構成になるよう具体的に手順を示していきます：
my_project/
├── pyproject.toml
├── uv.lock
├── .venv/
├── src/
│ └── main.py
├── tests/
│ └── test_main.py
└── README.mdpyproject.toml: 依存管理とプロジェクト設定ファイルuv.lock: ロックファイル（依存関係を固定）.venv/: 仮想環境ディレクトリsrc/: 実装コード置き場tests/: テストコードREADME.md: プロジェクト概要
uv initの実行
まずは初期化コマンドを実行します。
カレントフォルダをプロジェクトのルートフォルダにする場合は、
uv initカレントフォルダに新たに というフォルダを作って、プロジェクトのルートフォルダとする場合は、
uv init <PROJ_NAME>これにより pyproject.toml などのファイルが生成され、プロジェクトの基本が整います。
作られるファイルは、以下のとおりです。
- pyproject.toml
- 仮想環境のPythonバージョンを指定するための.python-version
- .gitignoreファイル
- サンプルのmain.py
- README.md
ファイル名やフォルダ構成を好みに合わせて適宜調整します。この段階ではvenv関連のフォルダやファイルは作られていません。
mkdir src
mv main.py ./src冒頭に示したフォルダ構成を実現するため、テスト用のファイルも作っておきます。
mkdir tests
touch test_main.py仮想環境の作成とアクティベート
仮想環境を作成するには、uvコマンドを実行します。プロジェクト環境のアップデートを行うコマンドを実行します。
uv syncこのコマンドによって仮想環境が作られます。フォルダは.venvとなります。最初にドットがついたフォルダ名なのでご注意ください。
同時に仮想環境が自動的にアクティベートされます。
依存パッケージの追加
たとえば、requestsパッケージを追加するには以下のようにします。
uv add requestsこれでpyproject.tomlに依存関係が追記され、uv.lockも自動で更新されます。
基本的なワークフロー
パッケージの更新
バージョンを指定して最新にアップデートもできます。
uv add fastapi@latest依存ファイルのロック
すでに手動でpyproject.tomlを編集した場合は、ロックファイルを更新します。
uv lockロックファイルから環境再構築
他の開発者が同じ環境を再現したいとき、ロックファイルから一発で構築できます。
uv syncこれでバージョン指定を含めて完全に同じ環境が構築されます。
スクリプト実行とデバッグ
依存を記述した単体スクリプトの実行
uvでは、ファイル冒頭に依存を記述するだけで、自動的にインストールして実行可能です。
# example.py
# requires: requests
import requests
print(requests.__version__)uv run example.py仮想環境やインストールを気にせず、すぐに実行できるのが便利です。
uvxを使ったCLIツールの実行（pipx代替）
たとえばリントツールの ruff を一時的に使う場合：
uv tool run ruff check src/インストール不要で実行でき、キャッシュされるため2回目以降は非常に高速です。
よく使うコマンドまとめ
| 用途 | コマンド例 |
|---|---|
| プロジェクト初期化 | uv init |
| パッケージ追加 | uv add package_name |
| ロックファイル生成 | uv lock |
| 環境再構築 | uv sync |
| 仮想環境作成 | uv venv |
| Pythonバージョン管理 | uv python install 3.12 |
| CLIツールの実行 | uv tool run httpie |
uvを使う際の注意点と補足
pyproject.tomlの構造に慣れる必要がありますが、近年のPython開発では標準的なフォーマットになりつつあります。poetryやpipenvとのlockファイル互換性は完全ではないため、移行時には注意が必要です。- uvは現在も急速に開発が進んでいるため、定期的なアップデート確認をおすすめします。
まとめ
- uvは
pip、venv、pyenv、pipx、poetryを統合したオールインワンの開発支援ツールです。 - プロジェクトの初期化から依存管理、環境構築、スクリプト実行までワンストップで完結します。
- 本記事の構成テンプレートを活用すれば、チーム開発やCI/CDにも対応可能な堅牢な環境を短時間で構築できます。
参考リンク
最後まで読んでいただきありがとうございました。
ご意見ご感想がありましたらコメント欄へよろしくお願いします。
コメント