uvの使い方｜pip・venvからの移行とチーム開発での使い方

uvとは、Pythonのパッケージのインストール、仮想環境の作成、Python本体のバージョン管理を、1つのツールでまとめて行えるツールです。Rustで作られていて動作が速く、これまで pip・venv・pyenv・pip-tools などを組み合わせていた作業を、uv コマンドだけで済ませられます。

uvには、pipと同じ感覚で使える uv pip のコマンドもありますが、本来の強みは uv init・uv add・uv run・uv sync を使ったプロジェクトの管理にあります。この記事では、基本の流れを実際に実行した結果つきで解説したうえで、pipからの移行、チームでの運用、DockerとGitHub Actionsでの使い方まで紹介します。

uvのコマンド早見表

インストール

インストールできたら、uv --version でバージョンを確認します。

基本の流れ：プロジェクトを作って動かす

1. プロジェクトを作る

uv init myapp
cd myapp

次のファイルが作られます（実行して確認）。

myapp/
├── .git/            # Gitのリポジトリも作られる
├── .gitignore
├── .python-version  # このプロジェクトで使うPythonのバージョン
├── README.md
├── main.py
└── pyproject.toml   # プロジェクトの設定と依存関係

2. パッケージを追加する

uv add requests
uv add --dev pytest

uv add を実行すると、次の3つがまとめて行われます。

• pyproject.toml に依存関係を書き込む
• uv.lock（ロックファイル）に、関連するパッケージを含めた正確なバージョンを記録する
• .venv（仮想環境）を作り、パッケージをインストールする

実行後の pyproject.toml は次のとおりです。

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.34.2",
]

[dependency-groups]
dev = [
    "pytest>=9.1.1",
]

開発用のパッケージは [dependency-groups] の dev に分けて記録されます。

3. 実行する

uv run main.py
uv run pytest
uv run python -c "import requests; print(requests.__version__)"

uv run は、仮想環境を有効化（activate）しなくても、プロジェクトの仮想環境で実行してくれます。実行の前に、pyproject.toml とロックファイル、インストール済みの環境が一致しているかを確認し、ずれていれば自動で揃えます。

4. 依存関係を確認する

uv tree

myapp v0.1.0
├── requests v2.34.2
│   ├── certifi ...
│   ├── charset-normalizer ...
│   ├── idna ...
│   └── urllib3 ...
└── pytest v9.1.1 (group: dev)

どのパッケージが、どのパッケージに必要とされているかを、ツリーで確認できます。

3つのファイルの役割

uv.lock をGitで共有することで、チームの全員が同じバージョンのパッケージで開発できます。「自分の環境では動くのに」という問題を減らせます。

チームで開発するときの流れ

リポジトリを取得した人

git clone https://github.com/example/myapp.git
cd myapp
uv sync

uv sync だけで、ロックファイルどおりの環境が揃います。Python本体が入っていない場合も、.python-version に書かれたバージョンを自動でダウンロードします。

ロックファイルが古くないかを確認する

uv sync --locked

--locked を付けると、pyproject.toml とロックファイルが一致しない場合に、ロックファイルを書き換えずにエラーで止まります（実行して確認）。

The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
To update the lockfile, run `uv lock`.

CIで使うと、「pyproject.tomlだけ変えて、ロックファイルの更新を忘れた」という状態を検出できます。

パッケージを更新する

uv lock --upgrade-package requests   # requestsだけを更新
uv lock --upgrade                    # すべてを更新
uv sync

Pythonのバージョン管理

uv python install 3.13          # Python 3.13をインストール
uv python list --only-installed # インストール済みのPythonの一覧
uv python pin 3.13              # このプロジェクトで使うバージョンを .python-version に書く

uv python pin で指定するバージョンは、pyproject.toml の requires-python の範囲内である必要があります。範囲外のバージョンを指定すると、次のようにエラーになります（実行して確認）。

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

pip・requirements.txtからの移行

既存のプロジェクトに requirements.txt がある場合は、次の手順で移行できます。

uv init --bare          # pyproject.tomlだけを作る（main.pyなどは作らない）
uv add -r requirements.txt
uv add --dev -r requirements-dev.txt

uv add -r で、requirements.txtのパッケージがまとめて pyproject.toml とロックファイルに登録されます。

requirements.txtが必要な環境（古いデプロイの仕組みなど）がある場合は、ロックファイルから書き出せます。

uv export --format requirements-txt --no-hashes > requirements.txt

すぐに移行できない場合は uv pip から

プロジェクトの構成を変えずに、速さだけを取り入れたい場合は、pipと同じ感覚で使える uv pip があります。

uv venv                               # .venv を作る
uv pip install -r requirements.txt    # pip install の代わり

uv pip は、既存の運用を変えずに試せる入り口です。慣れてきたら、uv add と uv sync を使ったプロジェクトの管理に移行すると、ロックファイルの恩恵を受けられます。

uvx：ツールをインストールせずに実行する

リンターやフォーマッターのようなプロジェクトの依存関係に含めないツールは、uvx で実行できます。

uvx ruff check .       # ruffを一時的な環境で実行
uvx ruff format .
uvx pycowsay "hello"

uvx は uv tool run の短縮形です。よく使うツールは、uv tool install ruff で常に使える状態にもできます。

1ファイルのスクリプトで依存関係を書く

プロジェクトを作るほどでもない1ファイルのスクリプトでも、ファイルの先頭に依存関係を書けます（PEP 723という標準の書き方）。

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///
import requests
print("ok", requests.__version__)

uv run script.py
uv add --script script.py rich   # 依存関係をスクリプトに追記

uv run で実行すると、必要なパッケージを入れた一時的な環境を自動で用意して実行します。社内の小さな自動化スクリプトを共有するときに便利です。

Dockerで使う

公式ドキュメントで紹介されている書き方をもとにした例です。

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

# 依存関係だけを先にインストール（コードを変えてもこの層はキャッシュが効く）
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev

# アプリのコードをコピーしてインストール
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev

CMD ["uv", "run", "main.py"]

GitHub Actionsで使う

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: astral-sh/setup-uv@v9
        with:
          enable-cache: true
      - run: uv sync --locked --dev
      - run: uv run pytest

uv sync --locked を使うことで、ロックファイルの更新漏れをCIで検出できます。公式ドキュメントでは、アクションやuvのバージョンを固定することを勧めています。

よくある質問

Q. Poetryやpipenvとの違いは何ですか？ A. どれも依存関係とロックファイルを管理するツールですが、uvはPython本体のインストール、ツールの実行（uvx）、1ファイルのスクリプトまで1つで扱える点と、処理の速さが特徴です。既存のプロジェクトが問題なく動いている場合は、急いで移行する必要はありません。

Q. 仮想環境を有効化（activate）する必要はありますか？ A. uv run を使う場合は不要です。エディタから仮想環境を使う場合などは、source .venv/bin/activate（Windowsは .venv\Scripts\activate）で従来どおり有効化もできます。

Q. condaとの違いは何ですか？ A. condaは、Python以外のライブラリ（CやFortranで書かれた科学計算用のライブラリなど）も含めて管理できるのが特徴です。一般的なWebアプリや業務システムの開発では、uvで十分なことがほとんどです。

Q. uv.lockは手で編集してもいいですか？ A. 編集しないでください。uv add・uv remove・uv lock で更新します。

まとめ

• uvは、パッケージ管理・仮想環境・Pythonのバージョン管理を1つで行える高速なツール
• 基本は uv init → uv add → uv run。仮想環境の有効化は不要
• uv.lock をGitで共有し、チームのメンバーは uv sync で同じ環境を揃える
• CIでは uv sync --locked で、ロックファイルの更新漏れを検出する
• 移行は uv add -r requirements.txt。まずは uv pip で試すこともできる
• ツールは uvx、1ファイルのスクリプトは先頭に依存関係を書いて uv run

株式会社RJCでは、新しい開発ツールを実際に試しながら、チームで使いやすい形を仲間と一緒に考えています。こうした知識を共有しながら、一緒に成長を楽しんでいます。

株式会社RJC ― SI事業・SES事業・AI駆動開発。未経験からエンジニアに育てるのが得意な会社です。