uvでPythonのバージョンを指定・変更する方法

uvでPythonのバージョンを指定・変更するコマンドと、実際に動かして分かった注意点をまとめます。

結論
動作確認した環境
Pythonをインストールする
プロジェクトのバージョンを指定する
プロジェクトのバージョンを変更する
1回だけ別のバージョンで実行する
プロジェクト外の既定のバージョンを決める
ハマりやすい点
パッチバージョンを上げる
MacとWindowsで直接使う場合の違い
参考

結論

やりたいこと	コマンド
Pythonをインストールする	`uv python install 3.12 3.13`
インストール済みのバージョンを見る	`uv python list --only-installed`
バージョンを指定してプロジェクトを作る	`uv init demo --python 3.12`
プロジェクトのバージョンを変更する	`uv python pin 3.13`
1回だけ別のバージョンで実行する	`uv run --python 3.12 python --version`
プロジェクト外の既定のバージョンを決める	`uv python pin --global 3.12`
Pythonをアンインストールする	`uv python uninstall 3.11`

動作確認した環境

uv 0.13.6
Dockerコンテナ(ghcr.io/astral-sh/uv:0.13.6-debian-slim、Debian 13)
uv以外のPythonが入っていない環境
確認日: 2026年10月31日

この記事は、MacとWindowsの両方の読者を対象にしています。本文の手順はDockerのコンテナ(Linux)の中で実行するので、MacでもWindowsでもDockerがあれば同じ手順で再現できます。WindowsのDocker Desktopは、Linuxコンテナを使う設定にしておきます。自分のPCに直接uvを入れて使う場合に、OSで違う点は「MacとWindowsで直接使う場合の違い」にまとめました。

この記事のコマンドは、Claude(AI)が1つのコンテナで上から順に実行して確認しました。章ごとに前の章の状態を引き継いでいるので、再現するときは順番どおりに実行してください。MacとWindowsに直接入れたuvでは確認していません。

同じ環境は、次のコマンドで用意できます。uvが入れたPythonを直接使えるように、最初にPATHを設定します。

$ docker run --rm -it ghcr.io/astral-sh/uv:0.13.6-debian-slim sh
# cd ~
# export PATH="$HOME/.local/bin:$PATH"

PATHを設定していないと、インストール時に ~/.local/bin がPATHにないという警告が出ます。以降の出力は、ダウンロードの進捗など一部を省略しています。プロンプトは $ で統一しています。

Pythonをインストールする

バージョンを並べると、まとめてインストールできます。

$ uv python install 3.12 3.13
Installed 2 versions in 4.87s
 + cpython-3.12.16-linux-x86_64-gnu (python3.12)
 + cpython-3.13.18-linux-x86_64-gnu (python3.13)

インストール済みのバージョンだけを見るには、--only-installed をつけます。つけない場合は、ダウンロードできるバージョンも一覧に出ます。

$ uv python list --only-installed
cpython-3.13.18-linux-x86_64-gnu    .local/bin/python3.13 -> .local/share/uv/python/cpython-3.13-linux-x86_64-gnu/bin/python3.13
cpython-3.13.18-linux-x86_64-gnu    .local/share/uv/python/cpython-3.13-linux-x86_64-gnu/bin/python3.13
cpython-3.12.16-linux-x86_64-gnu    .local/bin/python3.12 -> .local/share/uv/python/cpython-3.12-linux-x86_64-gnu/bin/python3.12
cpython-3.12.16-linux-x86_64-gnu    .local/share/uv/python/cpython-3.12-linux-x86_64-gnu/bin/python3.12

プロジェクトのバージョンを指定する

uv init の --python でバージョンを指定します。

$ uv init demo --python 3.12
$ cd demo
$ cat .python-version
3.12
$ grep requires-python pyproject.toml
requires-python = ">=3.12"
$ uv run python --version
Using CPython 3.12.16
Creating virtual environment at: .venv
   Building demo @ file:///root/demo
      Built demo @ file:///root/demo
Installed 1 package in 1ms
Python 3.12.16

指定は2つのファイルに入ります。.python-version は使うバージョン、pyproject.toml の requires-python はプロジェクトが対応する範囲です。

プロジェクトのバージョンを変更する

demo の中で uv python pin を実行すると、.python-version が書き換わります。次の uv run で、.venv が新しいバージョンで作り直されます。

$ uv python pin 3.13
Updated `.python-version` from `3.12` -> `3.13`
$ uv run python --version
Using CPython 3.13.18
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Installed 1 package in 3ms
Python 3.13.18

パッチバージョンまで指定することもできます。次の章に進む前に、3.13 に戻しておきます。

$ uv python pin 3.13.18
Updated `.python-version` from `3.13` -> `3.13.18`
$ uv python pin 3.13
Updated `.python-version` from `3.13.18` -> `3.13`

1回だけ別のバージョンで実行する

uv run に --python をつけます。.python-version は変わりません。

$ uv run --python 3.12 python --version
Using CPython 3.12.16
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Installed 1 package in 3ms
Python 3.12.16
$ cat .python-version
3.13

ただし、.venv は指定したバージョンで作り直されました。次に --python なしで実行すると、.python-version のバージョンでまた作り直されます。

$ uv run python --version
Using CPython 3.13.18
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Installed 1 package in 3ms
Python 3.13.18

--no-project をつけると、.venv は変わりませんでした。インストールしていないバージョンは、自動でダウンロードされます。

$ uv run --no-project --python 3.10 python --version
Downloading cpython-3.10.22-linux-x86_64-gnu (download) (28.0MiB)
 Downloaded cpython-3.10.22-linux-x86_64-gnu (download)
Python 3.10.22
$ .venv/bin/python --version
Python 3.13.18

プロジェクト外の既定のバージョンを決める

--global をつけると、~/.config/uv/.python-version に書き込まれます。プロジェクト外のディレクトリで試すと、そのディレクトリに .python-version を作った後は、そちらが優先されました。

$ uv python pin --global 3.12
Pinned `/root/.config/uv/.python-version` to `3.12`
$ mkdir ~/other && cd ~/other
$ uv python find
/root/.local/share/uv/python/cpython-3.12-linux-x86_64-gnu/bin/python3.12
$ uv python pin 3.13
Pinned `.python-version` to `3.13`
$ uv python find
/root/.local/share/uv/python/cpython-3.13-linux-x86_64-gnu/bin/python3.13

ハマりやすい点

requires-python より古いバージョンは指定できない

demo に戻って、requires-python の範囲外を指定するとエラーになります。今回の環境では、エラーが出る前にPython 3.11のダウンロードが行われました。

$ cd ~/demo
$ uv python pin 3.11
Downloading cpython-3.11.18-linux-x86_64-gnu (download) (29.2MiB)
 Downloaded cpython-3.11.18-linux-x86_64-gnu (download)
error: The requested Python version `3.11` is incompatible with the project `requires-python` value of `>=3.12`.
$ cat .python-version
3.13

下げるには、先に pyproject.toml の requires-python を変えてから、もう一度実行します。

$ sed -i "s/^requires-python = .*/requires-python = \">=3.11\"/" pyproject.toml
$ uv python pin 3.11
Updated `.python-version` from `3.13` -> `3.11`
$ uv run python --version
Using CPython 3.11.18
Removed virtual environment at: .venv
Creating virtual environment at: .venv
   Building demo @ file:///root/demo
      Built demo @ file:///root/demo
Installed 1 package in 1ms
Python 3.11.18

pythonコマンドが見つからない

通常のインストールでは、uvは python3.12 のようなバージョンつきのコマンドだけを追加し、python は追加しません。別の python が入っていない今回の環境では、コマンドが見つかりませんでした。エラーの表示はシェルによって異なります。

$ cd ~
$ python --version
python: not found
$ python3.12 --version
Python 3.12.16

python と python3 も使うには、--default をつけます。実行時の警告のとおり、このオプションは実験的な機能です。

$ uv python install --default 3.13
warning: The `--default` option is experimental and may change without warning. Pass `--preview-features python-install-default` to disable this warning
Installed Python 3.13.18 in 31ms
 + cpython-3.13.18-linux-x86_64-gnu (python, python3)
$ python --version
Python 3.13.18

プロジェクトの中で uv run python を使う分には、python コマンドがない状態でも実行できました。

アンインストールすると、そのバージョンの仮想環境は動かなくなる

uv venv で作った仮想環境のPythonは、アンインストール後に実行できなくなりました。

$ uv venv --python 3.11 ~/v311
$ ~/v311/bin/python --version
Python 3.11.18
$ uv python uninstall 3.11
Uninstalled Python 3.11.18 in 36ms
 - cpython-3.11.18-linux-x86_64-gnu
$ ~/v311/bin/python --version
/root/v311/bin/python: not found

uv venv で変えても uv run で戻ることがある

demo の .python-version を消して、先ほどの --global の設定(3.12)だけが残る状態で試しました。uv venv --python 3.13 で作った .venv が、次の uv run で3.12に作り直されました。プロジェクトのバージョンを変えるなら、uv python pin を使うほうが確実です。

$ cd ~/demo
$ rm .python-version
$ uv venv --python 3.13 --clear
Using CPython 3.13.18
Creating virtual environment at: .venv
$ uv run python --version
Using CPython 3.12.16
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Installed 1 package in 3ms
Python 3.12.16

自動ダウンロードを止めたいとき

--no-python-downloads をつけると、インストールしていないバージョンはダウンロードされず、エラーになります。ここでは、先ほど入った3.10をアンインストールしてから試します。

$ cd ~
$ uv python uninstall 3.10
Uninstalled Python 3.10.22 in 36ms
 - cpython-3.10.22-linux-x86_64-gnu
$ uv run --no-project --python 3.10 --no-python-downloads python --version
error: No interpreter found for Python 3.10 in virtual environments, managed installations, or search path

hint: A managed Python download is available for Python 3.10, but Python downloads are set to 'never'

パッチバージョンを上げる

公式ドキュメントによると、uv python upgrade は同じマイナーバージョンの最新パッチに上げるコマンドで、3.12から3.13のようには上がりません。今回の環境はすでに最新だったため、実際に上がるところは確認できていません。

$ uv python upgrade 3.13
Python 3.13 is already on the latest supported patch release

MacとWindowsで直接使う場合の違い

uv python install や uv python pin などのuvのコマンドは、OSによらず同じです。違うのは、uvのインストール方法、ファイルの置き場所、本文で使ったシェルの操作です。次の表は公式ドキュメントに基づくもので、MacとWindowsでは確認していません。置き場所は、XDG_DATA_HOME などの環境変数を設定していない場合のもので、Macの欄は公式ドキュメントの「Unix」の値です。

項目	Mac	Windows
uvのインストール	`curl -LsSf https://astral.sh/uv/install.sh \| sh` または `brew install uv`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` または `winget install --id=astral-sh.uv -e`
uvが入れたPythonの置き場所	`~/.local/share/uv/python`	`%APPDATA%\uv\data\python`
`python3.12` などのコマンドの置き場所	`~/.local/bin`	`%USERPROFILE%\.local\bin`
`--global` で作られる `.python-version`	`~/.config/uv/.python-version`	`%APPDATA%\uv\.python-version`
仮想環境のPython	`.venv/bin/python`	`.venv\Scripts\python.exe`

uvが入れたPythonの置き場所は、uv python dir で確かめられます(公式ドキュメント)。

本文の export、grep、sed、&& は、コンテナの中のLinuxのシェルで実行しています。自分のPCで同じことをするときは、次のように置き換えます。

本文の操作	Mac(ターミナル)	Windows(PowerShell)
uvのPythonのコマンドの置き場所をPATHに入れる	`uv python update-shell`	`uv python update-shell`
`requires-python` を確認する	`grep requires-python pyproject.toml`	`Select-String -Path pyproject.toml -Pattern 'requires-python'`
`requires-python` を書き換える	エディタで書き換える	エディタで書き換える
ディレクトリを作って移動する	`mkdir ~/other && cd ~/other`	`mkdir ~/other; cd ~/other`

uv python update-shell は、Pythonのコマンドの置き場所がPATHになければ、シェルの設定ファイルに追加するコマンドです(公式ドキュメント)。本文の export PATH=... と違って、今開いているシェルにはすぐには反映されない場合があります。実行後は、表示される案内に従い、新しいターミナルを開いてから続けてください。MacとWindowsでは実行していません。
本文の sed -i はLinuxの書き方で、Mac標準の sed では -i の後にバックアップの拡張子(不要なら '')が必要です(Appleの sed のマニュアル)。間違えやすいので、MacでもWindowsでもエディタで書き換えるのが確実です。
PowerShellの Select-String と、; で区切った mkdir と cd は、Windows 11 のPowerShell 7.6 とWindows PowerShell 5.1 で動くことを確認しました。Windows PowerShell 5.1 では && がエラーになりました。