公開日: 2025-06-01 更新日: 2025-06-01

概要

uv は Rust で実装された高速 Python パッケージ・プロジェクトマネージャ。 pyenv, venv, pip を置き換えるツールとして使用できる。非常に高速。 poetry からの乗り換え先として使用。

導入

python 未インストールの状態から導入可能 (Installation | uv)。

# Unix系
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# PyPI 経由
$ pip install uv

# 最新版へアップデート
$ uv self update

シェル環境へ設定を行う。以下のようにして ~/.bashrc へ入力補完の処理を追記する。 uvx はパッケージに収録されたツールをインストールせずに使うためのツール。

$ echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
$ echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc

アンインストールは以下の通り。

$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"

$ rm ~/.local/bin/uv ~/.local/bin/uvx

Python をインストール

uv から python をインストールして使うことが可能 (Installing and managing Python | uv)。バージョン指定 (Python versions | uv ) を入れる事で指定できる。

# インストール可能なバージョンの一覧を取得
$ uv python list

# インストール済みバージョンの一覧を取得
$ uv python list --only-installed
cpython-3.13.1-linux-x86_64-gnu
cpython-3.12.3-linux-x86_64-gnu

# 任意のバージョンをインストール
$ uv python install 3.12
$ uv python install cpython-3.12.3-linux-x86_64-gnu

# 再インストール
uv python install --reinstall

プロジェクトを作成

プロジェクトを作成し管理できる (Working on projects | uv)。作成時に python バージョンを指定する事で任意のバージョンを使用できる。省略時にはインストールされたものから最新版が選択される (Python versions | uv)。

# プロジェクトの python バージョンを明示する
$ uv init --python 3.11
# カレントディレクトリへ以下の様なファイルが生成される。
# (cwd)
#  ├ .python-version
#  ├ README.md
#  ├ main.py
#  └ pyproject.toml

$ uv init --bare
# カレントディレクトリへ以下の様なファイルが生成される。
# python バージョン指定などは追加しても機能しない。
# (cwd)
#  └ pyproject.toml

コードの実行。実行する際に仮想環境 (.venv) が作成され、内部で実行される。

uv run python main.py

仮想環境を作成

仮想環境は実行前に作成する事も可能。

Note

仮想環境を作成する事で以下のような事柄が実現できる：

  • 依存関係の分離：
    他システムと競合しないよう、専用の site-packages ディレクトリを持つ
  • 環境の再現性向上：
    プロジェクトごとに必要なパッケージだけで固定し、チームや CI 環境での同一動作を保証する

以下のコマンドで作成する。

# ディレクトリ下の python バージョンを指定 (.python-version)
$ uv python pin 3.13
$ uv python pin cpython@3.13

# 仮想環境 (.venv) を作成
$ uv venv

# 仮想環境 (.venv) を作成。
# 作成時に pip などをインストールする
$ uv venv --seed

依存関係を管理

プロジェクトへ依存関係を追加する (Working on projects | uv)。

# 依存関係を追加
$ uv add PACKAGE_NAME

# 依存関係を削除
$ uv remove PACKAGE_NAME

# 依存関係で pyproject.toml と .venv の状態を同期
$ uv sync