ブログ

uvがpip、virtualenv、pyenvを一気に置き換える。既に存在するプロジェクトのための移行ガイドです。

2026年4月30日 H.Ueda

こんにちは。皆さんは Python の開発環境を整えるとき、ツールが多すぎて「どれを使えばいいんだっけ？」と迷ったことはありませんか？

Python のバージョン管理には pyenv、仮想環境を作るには venv や virtualenv、パッケージを入れるには pip、さらに依存関係を固定するために pip-tools や Poetry を使う……。これらをバラバラに組み合わせて使うのは、少し手間がかかる作業ですよね。

最近、こうした複数のツールをたった一つで、しかも高速にこなしてくれる uv というツールが注目を集めています。今回は、既存のプロジェクトを uv へ移行する方法について、具体的に解説していきます。

uv とは何者か？

uv は、Rust で書かれた非常に高速な Python パッケージマネージャーです。これまでは「pip の高速版」という立ち位置でしたが、アップデートにより Python のバージョン管理やプロジェクト全体の管理もできるようになりました。

イメージとしては、これまでの「道具箱にバラバラに入っていた工具」を、一つの多機能ツール（マルチツール）にまとめるような感覚です。

ツール構成の変化

これまでの構成と uv を比較すると、以下のようなイメージになります。

flowchart TD
    subgraph Traditional["従来の構成 (バラバラなツール)"]
        A[pyenv] -- バージョン管理 --> Python
        B[virtualenv] -- 仮想環境 --> Env
        C[pip / pip-tools] -- インストール --> Packages
    end

    subgraph UV_Way["uv の構成 (統合ツール)"]
        D[uv] -- すべてを管理 --> AllInOne[Python / Env / Packages]
    end
機能 これまでのツール uv でのコマンド
Python バージョンの切り替え pyenv uv python
仮想環境の作成 venv / virtualenv uv venv
パッケージの追加 pip / poetry uv add
依存関係のロック pip-tools / poetry uv lock

既存プロジェクトを uv へ移行する手順

それでは、実際に pip や venv で管理していた既存プロジェクトを uv に移行する流れを見ていきましょう。

1. uv のインストール

まずは uv 本体のインストールです。以下のコマンド（macOS/Linux）で簡単に導入できます。

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

※ Windows の場合は、PowerShell で irm https://astral.sh/uv/install.ps1 | iex を実行してください。

2. プロジェクトの初期化

既存のプロジェクトディレクトリに移動して、uv プロジェクトとして初期化します。

uv init

これを実行すると、pyproject.toml という設定ファイルが作成されます。既存の requirements.txt がある場合は、それを読み込んで移行の準備をしましょう。

3. Python バージョンの指定

プロジェクトで使用する Python のバージョンを指定します。ここが pyenv を使っていた部分の代替になります。

uv python install 3.12
uv python pin 3.12

こうすることで、プロジェクト内で使用する Python のバージョンが固定されます。uv が必要に応じて適切なバイナリを自動でダウンロードしてくれるので、自分でインストールする手間が省けます。

4. パッケージの移行

既存の requirements.txt から依存関係を一括で取り込むことができます。

uv add -r requirements.txt

このコマンドを実行すると、uv は pyproject.toml を更新し、同時に uv.lock というファイルを作成します。これが Poetry や npm などの lock ファイルと同じ役割を果たし、チーム開発でも環境を完全に再現できるようになります。

5. 環境の同期（同期実行）

最後に、仮想環境を作成してパッケージをインストールします。

uv sync

これで、プロジェクト直下に .venv ディレクトリが作成され、すべてのパッケージがセットアップされます。驚くほど高速に終わるので、最初は「本当に終わったのかな？」と不安になるかもしれません。

uv を使うメリット

実際に移行してみると、以下のようなメリットを感じられるはずです。

  1. とにかく動作が軽い: Rust 製ということもあり、パッケージの解決やインストールが非常にスピーディーです。
  2. 設定が一つにまとまる: pyproject.toml だけを見ればプロジェクトの構成がわかるようになります。
  3. バイナリ単体で動く: uv は単一の実行ファイルなので、CI 環境などでのセットアップも簡単です。

たとえば、「新しい PC で開発を始める」というシーンでも、uv が入っていれば uv sync と打つだけで Python のインストールから環境構築まで完結します。

まとめ

uv は、これまでの Python 開発における「ツールの使い分け」という小さなストレスを解消してくれる存在です。既存のプロジェクトから移行するのも、コマンド数回で済むのでそれほど難しくありません。

まずは個人の小さなプロジェクトから、uv の快適さを試してみてはいかがでしょうか。きっと、もう元の pip や pyenv に戻るのが手間に感じてしまうはずですよ。

元記事

uv Is Replacing pip, virtualenv, and pyenv All at Once. Here’s a Migration Guide for Projects That Already Exist.

« 記事一覧へ戻る