uv教の侵略 ~venv教信者がuvに溺れるまで~

1. きっかけ

みんな大好き「からあげ」さんのこのポスト

試したくなりました。

結論：このSpeakerDeckを書いていただいた「MIKIO KUBO」さん、紹介していただいた「からあげ」さん、最高っす!

からあげさんはこの名著の著者のお一人です。

一度お会いしたことあるけど、サインもらい損ねた。💦

2. venvについて僕の過去記事

過去にはこんな記事書いてました。そう、ずっとvenvを使っていたんです。
それも自分でbashのエイリアスを書いて、バージョン違いもOKなふうにしてました。

そんな僕がゆらゆら揺れ動く事態にさせたのは、あなた！からあげさんです！（いじってみる。💦）

uvを使ってまだ一日目ですが、やはり初心者はvenv、初心者を脱却して様々なpythonバージョンを使い分ける必要が出てきたタイミングでuvへ移行で良いと思ってます。環境で悩まないことが初心者には大事なんじゃないかなと思います。（どんだけ苦労したか・・・）

3. MIKIO KUBOさんのSpeakerDeck

まじで神！

インストール等はこのまんまコピペ実行でOKデス。（mac、win11は大丈夫でした）

【追記】2015MacBook12inchに入れたubuntu24.04は以下でインストールできました。

sudo snap install astral-uv --classic

4. 僕のベストプラクティス（一つ目の方法）

まずは自分が半日色々と試行錯誤した結果のベストプラクティスを二つ紹介します。
ベスト！と言いながら二つあるけど許してん❤️

4.1 作業フォルダ（プロジェクト）の作成

なんでもいいので作業フォルダを作ります。
コマンドラインからmkdirでフォルダを作ってもいいし、Finder(mac)、explore(win)でもいいのでフォルダを作ります。
そしてbashやpowershellなどでこのフォルダに入ります。
cd <フォルダ名>/<子フォルダ名>でちまちま移動するか、cd と入力して作成したフォルダをドラッグ&ドロップします。

4.2 作業フォルダの初期化

pythonのバージョン指定をする初期化

uv init --python 3.11

ここ、かなり肝になります。使いたいpythonのバージョンはここで指定しましょう。

たとえば指定しないとどうなるかというと

pythonのバージョン指定しない初期化

uv init

この時に複数のファイルが作られますが、pyproject.tomlにrequires-python = ">=3.12"と記載されてしまいました。これだと例えば3.11の環境が作ると都度警告が出ます。なので、uv initの時にバージョン指定。これを忘れずに！

4.3 環境づくり

実はまだ悩んでますが、一旦これで。

uv venv

通常のvenvのイメージで作れます。
これで.venvフォルダが作られます。

win

 .venv\Scripts\activate

mac/linux

 source .venv\bin\activate

この辺りは普通のvenvと同じです。仮想環境に入ります。

4.4 ライブラリのインストール

インストールを行うためにrequirements.txtを用意しておきます。（てきとう）

requirements.txt

Django
numpy
pandas
matplotlib

uv add -r requirements.txt

これでライブラリのインストールができます。
ライブラリ一つ一つも簡単で、uv add numpyみたいに書けばいいだけです。

4.5 実行

ちょっとだけ実行方法が違います。いや、違いません。どっちやねん。
多分公式の実行方法はこれ

uv run main.py

いままではpython main.pyでしたね。ま、このくらいの変化は良いっすよね。
これであなたもuv教！！！

5. 僕のベストプラクティス（二つ目の方法）

「おい、今まで環境フォルダに名前付けてたやんけ！それも.venvって隠しフォルダにする意味も分からんって言うてたやんけ！」と言われそうですね。
ということで、環境フォルダに名前を付ける方法をやっていきます。

初期化までは飛ばして、仮想環境フォルダを作るところから簡単に紹介していきます。
（ここからはWindowsでの検証結果だけかきます。めずらしく、今日はWindows使っているので。ｗ）

uv venv proj_env
# uv venv <環境名>

実は、環境フォルダの名前を指定するのは簡単にできるんです。
通常のvenvとほぼ同じというかむしろ楽。

win

proj_env/Script/activate

仮想環境に入っていきましょう。先ほどとの違いは環境ファイル名が違うだけです。

uv add -r requirements.txt --active

ここから少し工夫が必要です。--activeをつける必要があるのです。
この--activeを忘れるとどうなるかと言うと、勝手に.venvが作られてしまいます。

この小さなミスで余分な容量を食うのはいただけません。
警告で止まればいいんだけど・・・（なぜこの仕様にした？）

uv run main.py

さて実行・・・と気軽に実行してはいけません。ｗ
これで実行すると、またも.venvが作られてしまい、その環境で実行されてしまいます。
だからなぜこの仕様なんだ？？

uv run　--active main.py

実は--activeを付ける必要があります。結構めんどくさい。
そこで従来の方法でやってみます。

python main.py

あ、今まで通りじゃん。w
なぜuv runがあるんだろ？

ということで、仮想環境フォルダを.venvから変えた場合、ひとまず普通にpython main.pyで実行するくらいで良いのかもしれません。
（何か困りごとが出てきたら追記します。）

6. 失敗事例

自部は初期化時（uv init)にpythonのバージョンを指定しわすれて、よくわからないことになってしまいましたので紹介します

uv init

こうすると自動生成されるpyproject.tomlはこうなります。

pyproject.toml

[project]
name = "test_proj"　
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

pythonのバージョンが3.12以上が指定されちゃうようです。

続けて仮想環境を作ります。ここでpythonのバージョン指定してみます。

uv venv proj_env --python 3.11
# warning: The requested interpreter resolved to Python 3.11.9, which is incompatible with the project's Python requirement: `>=3.12`

警告を出しながら、環境ができちゃう
そこで、仮想環境に入ってpythonのバージョンを確認してみましょう。

proj_env\Scripts\activate
(proj_env) PS <** 秘匿 **>/test_proj> python -V
Python 3.11.9

ちゃんとできてる

仮想環境を作った時の警告を無視してライブラリインストールすると

uv add -r requirements.txt
# warning: `VIRTUAL_ENV=proj_env` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead
# Using CPython 3.12.10
# Creating virtual environment at: .venv

3.12で.venv環境作られちゃう。💦
実は、--activeコマンドを付けても同様に3.12になっちゃいます。

じゃ、.venvで環境フォルダを作ったらどうなるか試してみました、同じ挙動になりました。
なので、tomlファイルのバージョン指定はかなり強力です。よって、uv init時にしっかりバージョン指定してあげることが一番大事だと思います。

気を付けるところのまとめ

• uv initするときにpythonのバージョンを指定するのを忘れない
  指定しないと、逆に3.12が指定されてしまうので警告が出る
• 環境フォルダを.venvから変えた場合はuv add時に--activeを忘れない
  忘れると.venvを勝手に作られる
• 環境フォルダを.venvから変えた場合はuv run時に--activeを忘れない
  忘れると.venvを勝手に作られる
• 環境フォルダを.venvから変えた場合はpython <ファイル名.py>で実行すると楽
• ここまで書いてないけど、ipynbで使う時はuv add ipykernelを忘れずに
  vscodeだと「ipykernelをインストールしないとノートブック形式はつかえんよ。インストールする？」って聞かれる。
  でも、YESとしてもpipがみつからないよ～と怒られてしまいます。なので手打ちでipykernelをインストールしてください。

7. おわりに

こうやって、venv教の信者はuv教に鞍替えしたのです。
しかしながら、この世界に入ってきたばかりの人にはvenv教をお勧めすることに変わりはありません。なぜなら、最初はpythonのバージョンはあまり気にしなくていいからです。
それよりも目的に合わせた仮想環境をきちんと作るといいうことに慣れたほうが良いと思います。

いずれ、このリポジトリを動かすには3.10じゃないとだめ！みたいな話が出てきます。その時にuv教の門をたたいても決して遅くないと思います。

こうしてvenv教信者だった私はuv教への入信をすることになりました。
ちゃんちゃん