🐍

Pythonパッケージ・プロジェクト管理ツール「uv」をインストールしてみた

に公開
Python
uv
tech

uvの概要

uvとはPythonのパッケージやプロジェクトを管理するAstral社製のOSSです。
uvだけでPythonのバージョン管理もパッケージ管理もできます。
また、uv自体はRustで書かれており、pipの10～100倍高速と謳われています。

uvをインストールしてみた

私はろくにコードを書かないので、pipやvenvだけで事足りていました。
しかし、下記のポストでuvを知って興味が湧いたため、試しに使ってみることにしました。
https://x.com/nakayoshix/status/1979734199050575886?s=20

uvをインストール

Windows OSの場合、以下のコマンドでuvをインストールします。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
実行結果
Downloading uv 0.9.8 (x86_64-pc-windows-msvc)
Installing to C:\Users\<USER_NAME>\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

To add C:\Users\<USER_NAME>\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\<USER_NAME>\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\<USER_NAME>\.local\bin;$env:Path"   (powershell)

実行結果にある通り、ターミナルを再起動するか$env:Path = "C:\Users\<USER_NAME>\.local\bin;$env:Path"というコマンドを打つと、uvコマンドが使えるようになります。

プロジェクトを作成

uvコマンドを打てるようになったら、uv initコマンドでプロジェクトを作成します。
今回はプロジェクト用のディレクトリを既に作成していたため、そのディレクトリまで移動してから以下のコマンドを実行しました。[1]

uv init --bare --python 3.13
実行結果
Initialized project `<PROJECT_DIRECTORY_NAME>`

一旦最小構成で始めたかったので、--bareオプションを付与したところ、pyproject.tomlだけ作成されました。

オプションを付与しないとどうなるの？

uv initコマンドをオプションなしで実行すると

  • .python-version（プロジェクトで使用するPythonのバージョンを記載）
  • README.md
  • main.py（サンプルコード）
  • pyproject.toml

が作成されます。

また、Python 3.13を使いたかったので、--pythonオプションでバージョンを指定したところ、pyproject.toml内のrequires-pythonが>=3.13となりました。

pyproject.toml
[project]
name = "agent-handson"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = []
オプションで指定しないとどうなるの？

uv initコマンドをオプションなしで実行すると、pyproject.toml内のrequires-pythonが>=3.14となります（2025/11/11時点）。
そのため、後々プロジェクトで使用するPythonのバージョンを3.13で固定しようとするとエラーが発生します。

uv python pin 3.13
実行結果
error: The requested Python version `3.13` is incompatible with the project `requires-python` value of `>=3.14`.

Pythonをインストール

Pythonのインストール前に利用可能なバージョンをuv python listコマンドで調べます。

uv python list
実行結果
cpython-3.15.0a1-windows-x86_64-none                 <download available>
cpython-3.15.0a1+freethreaded-windows-x86_64-none    <download available>
cpython-3.14.0-windows-x86_64-none                   C:\Users\<USER_NAME>\AppData\Roaming\uv\python\cpython-3.14.0-windows-x86_64-none\python.exe
cpython-3.14.0+freethreaded-windows-x86_64-none      <download available>
cpython-3.13.9-windows-x86_64-none                   <download available>
cpython-3.13.9+freethreaded-windows-x86_64-none      <download available>
cpython-3.12.12-windows-x86_64-none                  <download available>
cpython-3.11.14-windows-x86_64-none                  <download available>
cpython-3.10.19-windows-x86_64-none                  <download available>
cpython-3.9.24-windows-x86_64-none                   <download available>
cpython-3.8.20-windows-x86_64-none                   <download available>
pypy-3.11.13-windows-x86_64-none                     <download available>
pypy-3.10.16-windows-x86_64-none                     <download available>
pypy-3.9.19-windows-x86_64-none                      <download available>
pypy-3.8.16-windows-x86_64-none                      <download available>
graalpy-3.12.0-windows-x86_64-none                   <download available>
graalpy-3.11.0-windows-x86_64-none                   <download available>
graalpy-3.10.0-windows-x86_64-none                   <download available>

現時点で使う予定のないPython 3.14が存在するのは気持ち悪いので、一旦uv python uninstallコマンドでアンインストールしておきます。

uv python uninstall 3.14
実行結果
Searching for Python versions matching: Python 3.14
Uninstalled Python 3.14.0 in 330ms
 - cpython-3.14.0-windows-x86_64-none

そして、Python 3.13をuv python installコマンドでインストールします。

uv python install 3.13
実行結果
Installed Python 3.13.9 in 3.58s
 + cpython-3.13.9-windows-x86_64-none (python3.13.exe)

インストールしたPython 3.13をプロジェクトで使用するバージョンとしてuv python pinコマンドで固定します。

uv python pin 3.13
実行結果
Pinned `.python-version` to `3.13`

このコマンドの実行後、3.13とだけ書かれた.python-versionが作成されます。

キャッシュディレクトリを設定

Windows OSではuvのキャッシュディレクトリが既定でC:\Users\<USER_NAME>\AppData\Local\uv\cacheになります。
プロジェクトディレクトリをCドライブ以外（今回はFドライブ）に作成する場合、キャッシュディレクトリもプロジェクトディレクトリと同一のドライブにすると、uvのパフォーマンスが向上します。
そこで、環境変数UV_CACHE_DIRでキャッシュディレクトリを指定しておきます。

[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "F:\Users\<USER_NAME>\AppData\Local\uv\cache", "User")
実行結果（何も表示されません）

ターミナルを再起動し、正しく設定できたかどうかをuv cache dirコマンドで確認します。

uv cache dir
実行結果
F:\Users\<USER_NAME>\AppData\Local\uv\cache
環境変数を設定しないとどうなるの？

キャッシュディレクトリとプロジェクトディレクトリのドライブが異なる場合、パッケージのインストール時にハードリンクを作成できないことによるパフォーマンスの低下が警告されます。

uv add boto3
実行結果
Using CPython 3.13.9
Creating virtual environment at: .venv
Resolved 8 packages in 300ms
Prepared 7 packages in 1.88s
░░░░░░░░░░░░░░░░░░░░ [0/7] Installing wheels...
warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Installed 7 packages in 946ms
 + boto3==1.40.69
 + botocore==1.40.69
 + jmespath==1.0.1
 + python-dateutil==2.9.0.post0
 + s3transfer==0.14.0
 + six==1.17.0
 + urllib3==2.5.0

パッケージをインストール

試しにboto3をuv addコマンドでインストールしてみます。

uv add boto3
実行結果
Using CPython 3.13.9
Creating virtual environment at: .venv
Resolved 8 packages in 295ms
Prepared 7 packages in 1.45s
Installed 7 packages in 259ms
 + boto3==1.40.69
 + botocore==1.40.69
 + jmespath==1.0.1
 + python-dateutil==2.9.0.post0
 + s3transfer==0.14.0
 + six==1.17.0
 + urllib3==2.5.0

パッケージを正常にインストールすることができました。

スクリプトを実行

boto3を使った簡単なPythonスクリプトを用意します。

example.py
import boto3

def main():
    session = boto3.Session(profile_name="sandbox-main")
    sts = session.client("sts")
    response = sts.get_caller_identity()
    print(response["Account"])

if __name__ == "__main__":
    main()

uv runコマンドでスクリプトを実行します。

uv run example.py
実行結果
<AWS_ACCOUNT_ID>

スクリプトを正常に実行することができました。

Visual Studio Codeを設定

uv環境下でVisual Studio Codeを使って快適に開発できるよう設定していきます。
まず、インタープリタを指定します。
Ctrlキー＋Shiftキー＋Pキーを押下し、Python: Select Interpreterと入力します。
そこで、<PROJECT_DIRECTORY_PATH>\.venv\Scripts\python.exeを指定します。

次に、Visual Studio Code内のターミナルが仮想環境を自動で有効化できるように設定します。
Ctrlキー＋Shiftキー＋Pキーを押下し、Preferences: Open User Settings (JSON)と入力します。
settings.jsonが開いたら、以下を追記します。

    "terminal.integrated.profiles.windows": {
        "PowerShell (RemoteSigned)": {
            "source": "PowerShell",
            "args": ["-NoLogo", "-ExecutionPolicy", "RemoteSigned"]
        }
    },
    "terminal.integrated.defaultProfile.windows": "PowerShell (RemoteSigned)"

settings.jsonを保存してターミナルを起動すると、仮想環境が自動で有効化されます。

uvをインストールしてみた感想

本記事で触れたboto3以外にも様々なパッケージをuv addコマンドでインストールしてみましたが、やはりpipより断然速くて快適です。
インストールや設定が簡単で、公式ドキュメントも分かりやすいので、普段プログラミングをしない私のような方にも是非使ってみてほしいです。

脚注

  1. プロジェクトの作成と同時にディレクトリも作成したい場合はuv init <PROJECT_DIRECTORY_PATH>を実行します。 ↩︎

Discussion