この記事では、Windows + PowerShell を前提に、
uv でPython開発を開始する基本手順をまとめます。
対象環境：
- OS： Windows
- Sell： PowerShell
- Python： Python3
- Editor： VS Code
- MacOS 、 Linux 環境では、一部コマンドが異なります
- Windowsでも PowerShell以外 では一部コマンドが異なります
Pythonのバージョンを変更したくなった場合
uv venv したあとに、やっぱり別のPythonバージョンを使いたくなることがあります。
あとから使いたいライブラリが、そのPythonバージョンに、まだ対応していないことに気づいた場合とか・・・
この場合、既存の .venv の中にあるPythonを直接差し替えるのではなく、Pythonバージョンを指定し直して .venv を作り直すのが安全です。
考え方
正確には、これは「仮想環境のインタープリタを変更する」というより、仮想環境を再作成する手順です。
既存の .venv を無理に編集するより、削除して作り直す方がトラブルが少ないです。
手順1：仮想環境を抜ける
仮想環境を有効化している場合は、まず抜けます。
deactivate
手順2：既存の .venv を削除する
Remove-Item -Recurse -Force .venv
.venv フォルダを削除します。
手順3：使いたいPythonバージョンを指定して作り直す
例として、Python 3.12 を使う場合です。
uv venv --python 3.12
明示的に .venv を指定する場合は、次のように書いてもよいです。
uv venv .venv --python 3.12
手順4：仮想環境を有効化する
.\.venv\Scripts\Activate.ps1
手順5：Pythonバージョンを確認する
python --version
または、uv経由で確認します。
uv run python --version
任意のバージョンが出力されたら成功です。
お疲れ様でした。
uvプロジェクトとして管理している場合
uv init 済みのプロジェクトなら、Pythonバージョンもプロジェクト側で管理した方がわかりやすいです。
この場合は、uv python pin を使います。
uv python pin 3.12
これにより、.python-version が更新されます。
その後、.venv を削除・再構成・有効化を実施します。
Remove-Item -Recurse -Force .venv
uv venv --python 3.12
.\.venv\Scripts\Activate.ps1
最後に、uv sync で仮想環境と依存関係を再同期します。
uv sync
バージョンを確認します。
uv run python --version
pyproject.tomlのrequires-pythonも確認する
Pythonバージョンを変える場合は、pyproject.toml の requires-python も確認します。
たとえば、次のようになっている場合があります。
requires-python = ">=3.13"
この状態で Python 3.12 を使おうとすると、条件に合いません。
Python 3.12 以上を許可したい場合は、次のように変更します。
requires-python = ">=3.12"
Python 3.12系に固定したい場合は、次のようにします。
requires-python = ">=3.12,<3.13"
トラブルシューティング
キャッシュを削除したい場合
uvのキャッシュを削除したい場合は、次のコマンドを使います。
キャッシュが、原因で古いパッケージや壊れたデータを参照している可能性がある場合に使います。
🔹使っていないキャッシュだけ削除：
uv cache prune
🔹すべてのキャッシュを削除
uv cache clean
現在の依存関係を確認したい場合
uv pip list
または、Python標準の形式で確認します。
uv run python -m pip list
Pythonバージョン変更時のまとめ
# 仮想環境を抜ける
deactivate
# 使用Pythonバージョンをプロジェクトに固定
uv python pin 3.12
# 既存の仮想環境を削除
Remove-Item -Recurse -Force .venv
# lockファイルに基づいて仮想環境を再作成・同期
uv sync
# Pythonバージョン確認
uv run python --version