サイトアイコン アマチュア無線局JS2IIU

【Python】 uv初期構成テンプレート

JS2IIU

こんにちは、JS2IIUです。
Python開発において、パッケージ管理・仮想環境管理・依存関係の整理は避けて通れない重要なステップです。従来は pip、virtualenv、pipx、pyenv、poetry など複数のツールを組み合わせて対応していましたが、設定の煩雑さや処理速度の遅さに悩んだ方も多いのではないでしょうか。

そこで登場したのが「uv」です。Rustで書かれたこの新しいツールは、pipの10倍以上の速さを実現し、複数のツールの役割を1つに統合することで、高速かつシンプルなPython開発環境の構築を可能にします。

本記事では、uvを使ってプロジェクトを初期構成する方法を、実際のファイル構成とコマンド例を交えて丁寧に解説します。まずは本記事の手順に従ってお試しして、徐々に慣れていきましょう。今回もよろしくお願いします。

uvのインストール

まずは、uv本体のインストールから始めましょう。以下の方法で簡単にインストールできます。

推奨インストール方法（Unix/macOS/Windows）

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

Bash
pip install uv

バージョンを確認しておきます。

Bash
uv --version

なおuvの公式ページには他にも様々なインストール方法が紹介されています。お使いの環境に適した方法でインストールしてください。
Installation | uv

uvのコマンド

インストールできたら、次のコマンドを実行してみます。ヘルプが表示されます。ヘルプの一部を抜粋します。

Bash
uv
Plaintext
Commands:
  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を使って実際にプロジェクトを立ち上げる際のディレクトリ構成と初期設定の流れを紹介します。

ディレクトリ構成（例）

以下のような構成になるよう具体的に手順を示していきます：

Plaintext
my_project/
├── pyproject.toml
├── uv.lock
├── .venv/
├── src/
│   └── main.py
├── tests/
│   └── test_main.py
└── README.md

uv initの実行

まずは初期化コマンドを実行します。

カレントフォルダをプロジェクトのルートフォルダにする場合は、

Bash
uv init

カレントフォルダに新たに というフォルダを作って、プロジェクトのルートフォルダとする場合は、

Bash
uv init <PROJ_NAME>

これにより pyproject.toml などのファイルが生成され、プロジェクトの基本が整います。

作られるファイルは、以下のとおりです。

ファイル名やフォルダ構成を好みに合わせて適宜調整します。この段階ではvenv関連のフォルダやファイルは作られていません。

Bash
mkdir src
mv main.py ./src

冒頭に示したフォルダ構成を実現するため、テスト用のファイルも作っておきます。

Bash
mkdir tests
touch test_main.py

仮想環境の作成とアクティベート

仮想環境を作成するには、uvコマンドを実行します。プロジェクト環境のアップデートを行うコマンドを実行します。

Bash
uv sync

このコマンドによって仮想環境が作られます。フォルダは.venvとなります。最初にドットがついたフォルダ名なのでご注意ください。
同時に仮想環境が自動的にアクティベートされます。

依存パッケージの追加

たとえば、requestsパッケージを追加するには以下のようにします。

Bash
uv add requests

これでpyproject.tomlに依存関係が追記され、uv.lockも自動で更新されます。

基本的なワークフロー

パッケージの更新

バージョンを指定して最新にアップデートもできます。

Bash
uv add fastapi@latest

依存ファイルのロック

すでに手動でpyproject.tomlを編集した場合は、ロックファイルを更新します。

Bash
uv lock

ロックファイルから環境再構築

他の開発者が同じ環境を再現したいとき、ロックファイルから一発で構築できます。

Bash
uv sync

これでバージョン指定を含めて完全に同じ環境が構築されます。

スクリプト実行とデバッグ

依存を記述した単体スクリプトの実行

uvでは、ファイル冒頭に依存を記述するだけで、自動的にインストールして実行可能です。

Python
# example.py
# requires: requests
import requests

print(requests.__version__)
Bash
uv run example.py

仮想環境やインストールを気にせず、すぐに実行できるのが便利です。

uvxを使ったCLIツールの実行（pipx代替）

たとえばリントツールの ruff を一時的に使う場合：

Bash
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を使う際の注意点と補足

まとめ

参考リンク

最後まで読んでいただきありがとうございました。
ご意見ご感想がありましたらコメント欄へよろしくお願いします。

モバイルバージョンを終了