Python – パッケージ管理ライブラリ uv の使い方を解説

概要

この記事では、Python のパッケージ・プロジェクト管理ライブラリ uv の使い方について解説します。

uv の機能

uv は Rust で実装された高速なパッケージおよびプロジェクトの管理を実現します。

• pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv で行えることが uv 1 つで完結
• pip の 10 ～ 100 倍高速
• 依存関係のバージョンを固定するロックファイルを使用
• Python のバージョン管理機能
• pip と互換性がある CLI インタフェース
• macOS、Linux、Windows をサポート

インストール

各 OS ごとのインストール方法は Installation | uv を参考にしてください。 以下の方法の場合、インストーラーが PATH に uv のインストール先を追加するため、

• curl を使用してインストールする (Linux/Mac)

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

  Bash

  Copy

• PowerShell を使用してインストールする (Windows)

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

  PowerShell

  Copy

• pip を使用してインストールする

  pip install uv

  Bash

  Copy

uv の使い方

uv はプロジェクトを作成し、そのプロジェクトで使用する依存関係を管理するのが基本的な使い方になります。

手順 1. uv init でプロジェクトを作成する

uv init コマンドを使用してプロジェクトを作成します。

uv init [OPTIONS] [PATH]

以下のコマンドを実行すると、myapp ディレクトリ内に Python アプリケーション用のファイルが作成されます。

uv init --app myapp
cd myapp

myapp
├── README.md
├── main.py
└── pyproject.toml

手順 2. プロジェクトの依存関係を追加する

プロジェクトに必要な依存関係を uv add を使用して追加します。 依存関係の情報は pyproject.toml に記載されます。

uv add <PACKAGE>

pip と同様、依存関係指定子 に記載された方法で、追加するパッケージのバージョンを指定することも可能です。

• バージョン 2.0.0: uv add package==2.0.0
• バージョン 2.0.0 以上: uv add package>=2.0.0
• バージョン 2.0.0 以上、3 未満: uv add package>=2.0.0,<3.0.0

pip の requirements.txt からまとめて依存関係を追加することも可能です

uv add -r requirements.txt

プロジェクトから依存関係を削除するには、 uv remove を使用します。

uv remove <PACKAGE>

手順 3. 仮想環境を作成する

uv sync を使用して、依存関係の情報が記載された pyproject.toml の内容に基づき、venv による仮想環境を作成します。

uv sync

実行すると、.venv ディレクトリおよびロックファイル uv.lock が作成されます。 ロックファイルとは、プロジェクトの依存関係を厳密に管理するためのファイルです。これにより、異なる環境や時期においても、同じ依存関係がインストールされることを保証します。

以下のコマンドで仮想環境を有効・無効にできます。

• Linux/Mac
  • 仮想環境を有効にする: source .venv/bin/activate
  • 仮想環境を無効にする: deactivate
• Windows
  • 仮想環境を有効にする: .venv\Scripts\activate
  • 仮想環境を無効にする: deactivate

手順 4. アプリケーションを実行する

プロジェクト内のスクリプトファイルを仮想環境で実行するには、uv run <SCRIPT> を実行します。

uv run main.py

Python のバージョンを管理する

uv はシステムにインストールされた Python を検出して使用するようになっていますが、 pyenv のように指定したバージョンの Python をインストールする仕組みも存在します。

プロジェクトで指定したバージョンの Python を使用したい場合は、以下のコマンドで行います。

# 3.12 をインストールする
uv python install 3.12
# プロジェクトで 3.12 を使用する
uv python pin 3.12

pyproject.toml

--app または --lib の場合、pyproject.toml が作成されます。 このファイルには、プロジェクトの名前、説明およびバージョンといったメタ情報が含まれます。

pyproject.toml を書く – Python Packaging User Guide

[project]
name = "myapp"  # プロジェクト名
version = "0.1.0"  # バージョン
description = "Add your description here"  # 説明
readme = "README.md"  # README のパス
requires-python = ">=3.12"  # 要求する Python のバージョン
# 依存関係
dependencies = [
    "requests>=2.32.3",
]