1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

uv入門:pipとの違いと基本的な使い方

1
Posted at

はじめに

uvは、Ruffの開発元であるAstral社が開発しているRust製のPythonパッケージ・プロジェクト管理ツールです。pip・venv・pyenvなどの役割を1つのツールで担います。

本記事では、pipとの違いと、日常的に使う機能に絞って使い方を整理します。

動作確認環境:uv 0.12.18 / macOS(Apple Silicon)

pipとの違い

pip(+venv / pyenv) uv
速度 標準的 10〜100倍高速(公式値)
仮想環境 venv で作成し、activateが必要 自動で作成。activate不要
依存関係の記録 pip freeze で手動 pyproject.toml / uv.lock に自動記録
環境の再現 requirements.txt(間接依存は固定されにくい) uv.lock で間接依存まで固定
Pythonのバージョン管理 pyenvなど別ツール uv python で管理

1. 高速

依存関係の解決・ダウンロード・インストールをRustで並列処理します。また、グローバルキャッシュにより、一度ダウンロードしたパッケージは別プロジェクトでも再利用されます。numpy・pandas・torchなど大きなライブラリを繰り返しインストールする環境ほど差が出ます。

2. 1つのツールで完結

従来は目的ごとにツールを組み合わせる必要がありました。

用途 従来 uv
パッケージのインストール pip uv add
仮想環境の作成 venv / virtualenv 自動
依存関係の固定 pip freeze / pip-tools 自動(uv.lock)
Python本体の管理 pyenv uv python

3. 環境の再現性

requirements.txt は手動管理のため、記載漏れや間接依存のバージョンずれが起きがちでした。

uvは2つのファイルを自動で管理します。

  • pyproject.toml:直接追加したパッケージ
  • uv.lock:間接依存を含む、解決済みの正確なバージョン

別のPCやチームメンバーの環境でも、uv sync で同一の環境を再現できます。

4. 仮想環境の操作が不要

pipでは「venv作成 → activate → pip install」の手順が必要で、activateを忘れてグローバル環境にインストールしてしまうこともありました。

uvでは uv add や uv run の実行時に、プロジェクトの .venv が自動で作成・使用されます。

インストール

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

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

バージョンが表示されればインストール完了です。

uv --version

基本コマンド

日常的に使うのは次の5つです。

コマンド 内容
uv init プロジェクトを作成
uv add パッケージを追加
uv remove パッケージを削除
uv run プロジェクトの環境でコマンドを実行
uv sync uv.lock の通りに環境を揃える

uv init:プロジェクトを作成

uv init --no-package my-app
cd my-app
my-app/
├── .git/             # Gitリポジトリも初期化される
├── .gitignore
├── .python-version   # 使用するPythonのバージョン
├── README.md
├── main.py           # サンプルコード
└── pyproject.toml    # プロジェクト設定・依存パッケージ

既存のディレクトリでは、そのディレクトリ内で uv init --no-package を実行します。

--no-package について
uv 0.12時点では、uv init のデフォルトはパッケージ構成(--package)です。src/my_app/__init__.py と [build-system] が生成され、uv run my-app で実行する形になります。

uv init(デフォルト) uv init --no-package
構成 src/my_app/__init__.py main.py(フラット)
実行方法 uv run my-app uv run main.py
用途 配布・インポートするライブラリやCLI スクリプトとして動かすアプリケーション

本記事では、スクリプトを直接実行するシンプルな --no-package 構成で説明します。

pyproject.toml
[project]
name = "my-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

requires-python には、作成時に使われたPythonのバージョンが入ります(環境により異なります)。dependencies が requirements.txt に相当します。uv add / uv remove が自動で更新するため、手で編集する必要はありません。

uv add:パッケージを追加

uv add requests

pip install requests に相当しますが、次の処理がまとめて行われます。

  1. .venv が無ければ作成
  2. .venv にパッケージをインストール
  3. pyproject.toml の dependencies に追記
  4. 解決したバージョンを uv.lock に記録

実行後の pyproject.toml:

pyproject.toml
dependencies = [
    "requests>=2.34.2",
]

pipではインストール後に pip freeze > requirements.txt を別途実行する必要がありました。uvはインストールと記録が同時に行われるため、記録漏れが起きません。

バージョン指定

uv add "pandas>=2.0"      # 2.0以上
uv add "numpy==1.26.4"    # 固定

> や = はシェルで特別な意味を持つため、引用符で囲みます。

複数指定

uv add numpy pandas matplotlib

開発用パッケージ

テストやフォーマッタなど、実行時には不要で開発時のみ使うパッケージは --dev を付けます。

uv add --dev pytest

pyproject.toml の [dependency-groups] の dev に、通常の依存とは分けて記録されます。

uv remove:パッケージを削除

uv remove requests

.venv からアンインストールされ、pyproject.toml と uv.lock からも削除されます。pipのように、アンインストール後も requirements.txt に記載が残ることはありません。

uv run:コマンドを実行

uv run main.py

python main.py の代わりに使います。プロジェクトの .venv 内のPythonで実行されるため、activateは不要です。

# pip
source .venv/bin/activate
python main.py

# uv
uv run main.py

実行前に pyproject.toml と環境の整合性を確認し、不足しているパッケージがあれば自動でインストールします。

Python以外のコマンドも .venv 内で実行できます。

uv run pytest    # .venvのpytestを実行
uv run python    # .venvのPythonで対話モードを起動

VS Codeなどのエディタでは、インタープリタにプロジェクトの .venv を指定すると、補完やエラー表示が正しく機能します。

uv sync:環境を揃える

uv sync

uv.lock に記録されたバージョンで .venv を構築します。主な用途は次の通りです。

  • リポジトリをクローンした直後
  • 別のPCで同じ環境を作るとき
  • 他の開発者が追加・変更した依存関係を反映するとき

pipでの「venv作成 → activate → pip install -r requirements.txt」が1コマンドで済みます。ロックされたバージョンがそのまま入るため、環境差異による「手元では動く」問題を防げます。

pyproject.toml・uv.lock・.python-version はGit管理対象にします。.venv は uv sync でいつでも再作成できるためコミット不要です(uv init が生成する .gitignore で除外済み)。

使用例

Webページを取得する簡単なプログラムを作成します。

uv init --no-package hello-uv
cd hello-uv
uv add requests
main.py
import requests

def main():
    res = requests.get("https://example.com")
    print(res.status_code)

if __name__ == "__main__":
    main()
uv run main.py
# => 200

venvの作成、activate、requirements.txt の更新はいずれも行っていません。

別の環境では次の手順で再現できます。

git clone <リポジトリのURL>
cd hello-uv
uv sync
uv run main.py

Pythonのバージョン管理

「ライブラリが3.11までしか対応していない」「新規プロジェクトは3.13で作りたい」など、プロジェクトごとにPythonのバージョンを使い分ける場面は多くあります。従来はpyenvなどの別ツールが必要でしたが、uvはPython本体のインストールと切り替えも行えます。

一覧を確認

uv python list                   # 利用可能なバージョンとインストール済みのバージョン
uv python list --only-installed  # インストール済みのみ

uvでインストールしたものに加え、Homebrewや公式インストーラで導入済みのPythonも検出・利用されます。

インストール

uv python install 3.12            # 3.12系の最新
uv python install 3.11 3.12 3.13  # 複数
uv python install 3.12.4          # パッチバージョン指定

uv専用のディレクトリに配置されるため、システムのPythonには影響しません。複数のバージョンは並存し、新しいバージョンを入れても既存のバージョンが消えることはありません。

プロジェクト作成時に指定

uv init --no-package my-app --python 3.11

.python-version が 3.11、pyproject.toml の requires-python が >=3.11 になります。

requires-python は、そのプロジェクトで使えるバージョンの下限になります。複数バージョンを切り替えて使う予定がある場合は、使う中で最も古いバージョンを指定して作成します。

バージョンを切り替える

インストール済みの複数バージョンは、用途に応じて次の3つの方法で切り替えます。

切り替えの範囲 コマンド pyenvでの相当
プロジェクト単位 uv python pin <バージョン> pyenv local
プロジェクト外のデフォルト uv python pin --global <バージョン> pyenv global
1回の実行のみ uv run --python <バージョン> ... pyenv shell

プロジェクト単位で切り替える

# 3.11と3.13をインストール(並存する)
uv python install 3.11 3.13

# 3.11以上に対応するプロジェクトを作成
uv init --no-package my-app --python 3.11
cd my-app

# 3.13に切り替え
uv python pin 3.13
uv run python --version
# => Python 3.13.x

# 3.11に切り替え
uv python pin 3.11
uv run python --version
# => Python 3.11.x

uv python pin は、プロジェクトで使うバージョンを .python-version に設定します。切り替えるのは「どのバージョンを使うか」の指定だけで、インストール済みのPythonはそのまま残ります。

切り替え後の uv run / uv sync 実行時に、uvが .venv とのバージョン不一致を検出し、.venv を指定バージョンで再作成してパッケージを再インストールします。

pyenvでは「Pythonの切り替え → 仮想環境の再作成 → パッケージの再インストール」を手動で行う必要がありましたが、uvではすべて自動です。

プロジェクト外のデフォルトを切り替える

uv python pin --global 3.12

.python-version が無いディレクトリで、uvが使うデフォルトのバージョンを設定します。設定は ~/.config/uv/.python-version に保存され、uv python pin --global --rm で解除できます。

1回の実行だけ切り替える

uv run --python 3.13 python --version

別バージョンでの動作を一度だけ確認したい場合に使います。.python-version は変更されないため、プロジェクトの設定はそのままです。なお、このとき .venv は指定バージョンで再作成され、次に --python なしで uv run を実行すると .python-version のバージョンで再作成されます。

requires-python の範囲外のバージョンには切り替えられません。たとえば requires-python = ">=3.12" のプロジェクトで uv python pin 3.11 や uv run --python 3.11 を実行するとエラーになります。

error: The requested Python version `3.11` is incompatible with the project `requires-python` value of `>=3.12`.

古いバージョンに切り替える場合は、先に pyproject.toml の requires-python を ">=3.11" などに変更してください。

.python-version と requires-python

設定 場所 意味
.python-version .python-version 開発環境で実際に使うバージョン(例:3.12)
requires-python pyproject.toml プロジェクトが対応するバージョンの範囲(例:>=3.12)

バージョンの切り替えは、通常 .python-version を uv python pin で設定すれば十分です。

自動ダウンロード

指定したバージョンがインストールされていない場合、uv init --python、uv python pin 後の uv run / uv sync などの実行時に自動でダウンロードされます。そのため、通常は uv python install を明示的に実行しなくても、バージョンを指定するだけで動作します。

削除

uv python uninstall 3.11

削除対象はuvでインストールしたPythonのみです。Homebrewなどで導入したPythonは削除されません。

pipとのコマンド対応

操作 pip / pyenv uv
仮想環境の作成 python -m venv .venv 不要(自動)
仮想環境の有効化 source .venv/bin/activate 不要
パッケージの追加 pip install requests uv add requests
パッケージの削除 pip uninstall requests uv remove requests
依存関係の記録 pip freeze > requirements.txt 不要(自動)
環境の再現 pip install -r requirements.txt uv sync
実行 python main.py uv run main.py
Pythonのバージョン切り替え pyenv install 3.12 → pyenv local 3.12 → venv再作成 uv python pin 3.12

従来手作業で行っていた操作の多くが、uvでは不要または自動化されています。

まとめ

  • uvはpip・venv・pyenvの役割を1つにまとめた、Rust製の高速なPython管理ツール
  • 基本操作は uv init・uv add・uv remove・uv run・uv sync の5つ
  • 仮想環境の作成・activate・依存関係の記録は自動で行われる
  • uv.lock と uv sync により、どの環境でも同一の構成を再現できる
  • Pythonのバージョンは uv python pin でプロジェクトごとに切り替えられる

参考

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?