探索 uv#
なぜ私は uv に関する完全な中国語の文書やチュートリアルを見つけられないのか。
pip の悪の勢力が強すぎるのか？いいえ、単に人々が未知のものを受け入れることに恐怖心を抱いているだけだと思います。
私の探索の過程とルートを記録するので、非常に混乱するでしょう。
uv とは何ですか？#
立方体の表面を線に沿って切り開き、すべての面を展開すると、uv マッピングが得られます。uv テクスチャを利用してモデルにテクスチャを貼ることができます。
...
ぺぺぺ、ここで私たちが話す uv は、パッケージ管理ツールです。
これは uv と pip のインストール速度の比較です。
ここでは、いくつかの uv の基本的な使い方を探求し、pip のいくつかの代替方法を紹介します。また、後で自分の最初の Python パッケージをコンパイルすることを試みます。（Github からインストールして実行できれば大丈夫です）
ああ、ちなみに、私の記録の仕方が不快に感じるか、見づらいかもしれませんが、理解しています。なぜなら、私は自分の探索のルートに従って書いているからです。思いついたところで実験して、それを書き留めています。これが私の学びの全体的な考え方です。
今後、使い方を整理するかもしれません。
参考文献:#
uv.lock + pyproject.toml vs requirements.txt#
uv.lock は手動で uv lock を実行した後に生成され、pyproject.toml に基づいており、通常は手動で変更すべきではありません：
uv.lock は人間が読める TOML ファイルですが、uv によって管理されており、手動で編集すべきではありません。
最初は uv.lock が pyproject.toml の Python 依存関係の設定を置き換えることができると思っていましたが、実際には強化されていることがわかりました。
uv add package -> uv lock -> uv run / uv sync -> uv run:
依存関係を迅速に変更し、互換性があるかどうかを検証できます。
また、Github リポジトリから直接サードパーティライブラリをインストールすることもサポートしており、パッケージ依存関係の処理が非常に細かくなります。
途中で uv.lock を更新する場合も、最初に pyproject.toml を更新し、その後に uv lock を実行します。
さらに、uv.lock は非常に安全感を与えます。もしあなたが特に uv.lock の内容を見たことがあるなら、どこからインストールされたか正確に記録されています。それに対して requirements.txt は非常に雑です。
pyproject.toml はプロジェクトの広範な要件を指定するために使用されるのに対し、lockfile にはプロジェクト環境にインストールされた正確な解決済みバージョンが含まれています。このファイルはバージョン管理にチェックインされるべきであり、異なるマシン間で一貫した再現可能なインストールを可能にします。
pyproject.toml + uv.lock の形式では、人間が読める部分は pyproject.toml であり、uv.lock は機械が読むためのものです。一方、pip freeze によって生成された requirements は、人間にも機械にも理解できません。
uv add の形式を通じて、各パッケージのバージョンとライブラリは少しずつ構築され、確定されていきます。直接 freeze されるわけではありません。
pyproject.toml には必須のパッケージとそのバージョンがリストされ、依存パッケージは自動的にダウンロードされます。これも、uv add の際には依存パッケージではなく必須パッケージのみを追加することをお勧めします。
一方、pip freeze の requirements.txt はすべて依存パッケージであり、全く人間が読むためのものではありません。
時々、私は依存パッケージを手書きすることを考えますが、requirements.txt を手書きするのは非常に忍耐力を試されます。
そして、私が面倒なとき：
私が提供する requirements.txt は次のようになります：
pyaml
gradio
そして、あなたは新しいクリーンな環境を再作成し、pip install -r requirements.txt を実行して、これが完全であるかどうかを検証する必要があります。
uv add -> uv lock -> uv run script のすべての依存関係は、環境での実行がサポートされているかどうかを迅速に確認できます。なぜなら、uv run は uv.lock のみを基に実行されるからです。
また、もし私が上記の手書きの requirements.txt（バージョン指定なし）を使用した場合、私は確信しています。私のユーザーは 3 ヶ月後のある日、特定の API が廃止されたり、最新バージョン同士が互換性がないことに気づくでしょう。
Windows では、最新バージョンの pyaml と gradio がダウンロードされます。もし私が長い間更新していなければ、問題が発生する可能性が高いです。
Linux では、さらにひどいことになります。すべてのバージョンの pyaml と gradio がダウンロードされます。これはバグなのかどうかはわかりませんが、とにかく少なくとも 5 つのバージョンの gradio がダウンロードされ、最後にいくつかがインストールされました。
偶然の機会に、私は uv を始めることに決めました。その公式文書から、この決定を下すことになり、以前の心理的な影を克服せざるを得ませんでした。つまり、gpt に何も理解できないと言われ、逆に多くの誤解を招いてしまったのです。
彼は私に uv pip install uv.lock を使うように言いました..... 私は本当に...
しかし、始める前に、私は自分で uv を一度試してみる必要があります。結局、このものの完全な中国語文書が見つからないのです。pip の悪の勢力が強すぎるのか？いいえ、単に人々が未知のものに対して恐怖心を抱いているだけだと思います。私はかなり早くから理解したいと思っていましたが、今まで引き延ばしてしまいました。これは偶然の機会です。
uv のインストールと最終的な提案。#
https://docs.astral.sh/uv/getting-started/installation/
私の最終的な提案は、uv をグローバルにインストールし、pyproject.toml と uv.lock を使用してプロジェクト（Python ライブラリ）を管理することです。
具体的な参考文献：
https://github.com/yutto-dev/yutto
https://github.com/MrXnneHang/yutto-uiya
または、便利さのために、単に uv + conda を使用して pip + conda を置き換えることもできます。使い方は、すべてを次のように置き換えます：
pip install -> uv pip install.
uv run の開始： uv run python/yutto/... の実行可能ファイルはどこにありますか？#
あの人のブログで書かれている uvv のような全体的な方法を考慮しない場合、通常の uv 環境はプロジェクトのルートディレクトリの .venv の下にあります。
uv run を記述することは、以前の conda で指定された仮想環境下で python/yutto にアクセスできるのと同じです。
Python は一般的に .venv/bin の下にあります。
uv を独立して使用して venv を作成する。#
言及する価値があります。Linux で miniconda を最初にインストールする際に、auto_activate_base を有効にするかどうかを選択させられます。つまり、ターミナルに入るたびに base 環境を自動的にアクティブにするかどうかです。uv を独立して使用しようとする場合、このオプションを最初に無効にすることを考慮すべきです：
さもなければ、作成された venv はすべて現在の仮想環境の Python バージョンになります。
conda config --set auto_activate_base false
その後、新しいターミナルを開くと、base 環境は自動的にアクティブになりません。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv venv
Using CPython 3.13.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ ls .venv/
bin CACHEDIR.TAG lib lib64 pyvenv.cfg
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ ls .venv/bin/
activate activate.csh activate.nu activate_this.py pydoc.bat python3
activate.bat activate.fish activate.ps1 deactivate.bat python python3.13
どうやら、3.13 の Python 基本環境が直接作成されたようです。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python tmp.py
Hello UV!
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run tmp.py
Hello UV!
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python
Python 3.13.0 (main, Oct 16 2024, 03:23:02) [Clang 18.1.8 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
正常に動作しているようです。
また、環境を作成する際の速度が非常に速いことに驚きました？半秒？
これは次の理由によるようです：
Python がすでにシステムにインストールされている場合、uv はそれを検出して構成なしで使用します。ただし、uv は Python バージョンをインストールおよび管理することもできます。uv は必要に応じて不足している Python バージョンを自動的にインストールします。Python をインストールせずに始めることができます。
この機能を利用して、conda から必要な Python バージョンを直接取得することもできます。具体的には次のセクションで説明します。
指定されたバージョンの Python をインストールするには？#
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv python install 3.12
Installed Python 3.12.9 in 53.73s
+ cpython-3.12.9-linux-x86_64-gnu
これは再度インストールされました。上記から判断すると、システムに 3.12 の Python バージョンが存在しないためです。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python
Python 3.13.0 (main, Oct 16 2024, 03:23:02) [Clang 18.1.8 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python3.12
Python 3.12.4 (main, Jul 9 2024, 09:31:23) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python3.11
error: Failed to spawn: `python3.11`
Caused by: No such file or directory (os error 2)
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ ls .venv/bin/
activate activate.csh activate.nu activate_this.py pydoc.bat python3
activate.bat activate.fish activate.ps1 deactivate.bat python python3.13
3.12 をインストールしたことは、.venv にはインストールされていないようです。.venv を削除した後、再度 uv run python3.12 を実行しても、依然として動作します。これはグローバルにインストールされていることを示しています。
これは実際にはいくつかの恐ろしいリスクを伴います。グローバルな Python は常にいくつかの抜け道が存在します。たとえば、uv run python -m pip install matplotlib を使用すると、グローバル環境を直接汚染することができます。
したがって、ここで私が個人的に考えるより良い方法は、conda を利用して 3.10、3.11、3.12 の環境を管理し、必要なときに conda から環境を ./venv にコピーすることです。その後、すべての環境変更は ./venv に対して行われます。
venv に Python バージョンを指定する：#
システム全体の Python に比べて、conda の仮想環境はより安全で管理が容易です。私たちは異なる初期パッケージをカスタマイズすることさえできます。たとえば、初期の selenium、webdriver を使用してクローリング作業を行ったり、初期の numpy、matplotlib を使用してデータ分析作業を行ったりします。そして、使用する際にそれを .venv にコピーします。
私の後半の考えは間違っていました。なぜなら、uv venv は Python を継承するだけで、パッケージを継承しないからです。次の内容がこれを証明します。
この点で、私はその著者と意見が一致しました：
conda activate 11
uv venv --seed -p 3.11
conda deactivate
uv pip install -r requirements.txt
source ./.venv/bin/activate
python main.py
パラメータの解析：
-p, --python <PYTHON>
仮想環境に使用する Python インタプリタ。[env: UV_PYTHON=]
--seed
仮想環境にシードパッケージ（`pip`、`setuptools`、`wheel` のいずれかまたはすべて）をインストールします。[env: UV_VENV_SEED=]
私は、私が想像していたような「コピー」が発生しないことに気づきました。おそらく環境をコピーするのではなく、Python を継承しているだけです。
それは、uv venv を実行する際に、システムの優先 Python をデフォルトで検出することを利用しています。そして、conda activate 11 を実行すると、デフォルトで python XXX を実行するのは conda の Python です。したがって、uv venv はこの Python を継承します。
それがパッケージを継承するかどうかをテストしてみましょう。
venv の作成が仮想環境のパッケージを継承するかどうかのテスト#
結論から言うと、継承しません。Python のみを継承します。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ conda activate numpy
(numpy) xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ python
Python 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> exit()
(numpy) xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ conda deactivate
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ conda activate numpy
(numpy) xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ python
Python 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> numpy.__version__
'2.2.2'
>>> exit()
(numpy) xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv venv -p 3.10 --seed
Using CPython 3.10.16 interpreter at: /home/xnne/miniconda3/envs/numpy/bin/python3.10
Creating virtual environment with seed packages at: .venv
+ pip==25.0.1
+ setuptools==75.8.0
+ wheel==0.45.1
Activate with: source .venv/bin/activate
(numpy) xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ conda deactivate
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python
Python 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'numpy'
>>>
Using CPython 3.10.16 interpreter at: /home/xnne/miniconda3/envs/numpy/bin/python3.10 これは、確かに私たちの conda 環境の Python を使用していることを示しています。しかし、パッケージは継承されていません。
uv run pip install と uv pip install の違い：#
uv run pip install vs pip install:#
結論から言うと、uv run pip install は .venv にインストールされ、uv run python -m pip install と同じ効果があります。
前述のように、通常の pip install を使用する場合、仮想環境内で使用する pip install はグローバル環境を汚染しません。なぜなら、仮想環境がアクティブな場合、仮想環境の優先度がシステム環境よりも高いため、pip install は仮想環境にインストールされるからです。
私たちの uv は、局所的な .venv を作成しただけです。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python
Python 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'numpy'
>>> exit()
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run pip install numpy
Collecting numpy
Using cached numpy-2.2.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (62 kB)
Using cached numpy-2.2.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.4 MB)
Installing collected packages: numpy
Successfully installed numpy-2.2.3
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run python
Python 3.10.16 (main, Dec 11 2024, 16:24:50) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>> numpy.__version__
'2.2.3'
>>>
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ ls .venv/lib/python3.10/site-packages/
_distutils_hack numpy.libs __pycache__ _virtualenv.py
distutils-precedence.pth pip setuptools wheel
numpy pip-25.0.1.dist-info setuptools-75.8.0.dist-info wheel-0.45.1.dist-info
numpy-2.2.3.dist-info pkg_resources _virtualenv.pth
一方、直接 pip install を実行すると、私のシステム環境には実際には pip が存在しません。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ pip uninstall numpy
bash: pip: コマンドが見つかりません
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ pip install numpy
bash: pip: コマンドが見つかりません
これは、uv が私たちのシステム環境を直接隔離しているわけではなく、現在のディレクトリに .venv を作成していることを示しています。すべての uv run XXX はこの .venv 内で操作されています。
uv pip install vs uv run pip install:#
結論から言うと、両者は .venv の環境に対して操作を行います。
しかし、uv run pip install は pip を使用して環境をインストールし、uv pip install は uv を使用して環境をインストールします。
速度の比較を見てみましょう：
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ time uv run pip install numpy
Collecting numpy
Using cached numpy-2.2.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (62 kB)
Using cached numpy-2.2.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.4 MB)
Installing collected packages: numpy
Successfully installed numpy-2.2.3
real 0m3.090s
user 0m1.770s
sys 0m0.163s
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv pip uninstall numpy
Uninstalled 1 package in 55ms
- numpy==2.2.3
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ time uv pip install numpy
Resolved 1 package in 16ms
Installed 1 package in 31ms
+ numpy==2.2.3
real 0m0.064s
user 0m0.007s
sys 0m0.054s
すごい、速度がまったく異なります。
つまり、環境をインストールする際には、uv pip install を多く使用するべきです。
uv を使用して pip の作業を置き換える方法を簡単にまとめます。
#
もしあなたが miniconda を使用していて、uv をパッケージインストールの加速に使用したいだけなら、環境を作成した後、次のようにします：
pip install uv
uv pip install -r requirements.txt/packagename
これが最も簡単な方法だと思います。
もし私のように統合パッケージを作成する習慣があるなら、プロジェクトのルートディレクトリに環境をパッケージ化することを試みることができます。次のようにします：
conda activate 10
uv venv --seed -p 3.10
conda deactivate
uv pip install -r requirements.txt/packagename
この uv はグローバルにインストールする必要があります。上記のリンクを参照してください。
また、uv が特定のパッケージをインストールできない場合は、再度 pip を使用する必要があります。これが私が上記で uv pip と uv run pip について多くの時間を費やした理由です。
たとえば：
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run __main__.py
Traceback (most recent call last):
File "/home/xnne/code/yutto-uiya/src/uiya/__main__.py", line 3, in <module>
import gradio as gr
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/__init__.py", line 3, in <module>
import gradio._simple_templates
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/_simple_templates/__init__.py", line 1, in <module>
from .simpledropdown import SimpleDropdown
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/_simple_templates/simpledropdown.py", line 7, in <module>
from gradio.components.base import Component, FormComponent
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/components/__init__.py", line 1, in <module>
from gradio.components.annotated_image import AnnotatedImage
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/components/annotated_image.py", line 14, in <module>
from gradio import processing_utils, utils
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/gradio/processing_utils.py", line 120, in <module>
sync_client = httpx.Client(transport=sync_transport)
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/httpx/_client.py", line 697, in __init__
self._mounts: dict[URLPattern, BaseTransport | None] = {
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/httpx/_client.py", line 700, in <dictcomp>
else self._init_proxy_transport(
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/httpx/_client.py", line 750, in _init_proxy_transport
return HTTPTransport(
File "/home/xnne/code/yutto-uiya/src/uiya/.venv/lib/python3.10/site-packages/httpx/_transports/default.py", line 191, in __init__
raise ImportError(
ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv pip install https[socks]
× No solution found when resolving dependencies:
╰─▶ Because there are no versions of https[socks] and you require https[socks], we can conclude that
your requirements are unsatisfiable.
私は uv pip install を使用して httpx[socks] をインストールできないため、この場合は uv run pip install に戻る必要があります。
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run pip install httpx[socks]
Requirement already satisfied: httpx[socks] in ./.venv/lib/python3.10/site-packages (0.28.1)
Requirement already satisfied: anyio in ./.venv/lib/python3.10/site-packages (from httpx[socks]) (4.8.0)
Requirement already satisfied: certifi in ./.venv/lib/python3.10/site-packages (from httpx[socks]) (2025.1.31)
Requirement already satisfied: httpcore==1.* in ./.venv/lib/python3.10/site-packages (from httpx[socks]) (1.0.7)
Requirement already satisfied: idna in ./.venv/lib/python3.10/site-packages (from httpx[socks]) (3.10)
Collecting socksio==1.* (from httpx[socks])
Using cached socksio-1.0.0-py3-none-any.whl.metadata (6.1 kB)
Requirement already satisfied: h11<0.15,>=0.13 in ./.venv/lib/python3.10/site-packages (from httpcore==1.*->httpx[socks]) (0.14.0)
Requirement already satisfied: exceptiongroup>=1.0.2 in ./.venv/lib/python3.10/site-packages (from anyio->httpx[socks]) (1.2.2)
Requirement already satisfied: sniffio>=1.1 in .venv/lib/python3.10/site-packages (from anyio->httpx[socks]) (1.3.1)
Requirement already satisfied: typing_extensions>=4.5 in .venv/lib/python3.10/site-packages (from anyio->httpx[socks]) (4.12.2)
Using cached socksio-1.0.0-py3-none-any.whl (12 kB)
Installing collected packages: socksio
Successfully installed socksio-1.0.0
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv run __main__.py
* Running on local URL: http://127.0.0.1:7860
To create a public link, set `share=True` in `launch()`.
解決しました。
uv lock、環境を固定する。#
これを実行するには、まず pyproject.toml が必要です。
これは Python + ruff の簡単な設定です：https://github.com/MrXnneHang/yutto-uiya/blob/gradio-webui/pyproject.toml
その後、次のように実行します：
xnne@xnne-PC:~/code/yutto-uiya/src/uiya$ uv lock
Using CPython 3.13.0
Resolved 1 package in 4ms
何もパッケージがロックされていないように見えます。もし pyproject.toml に次のように提供されていなければ：
[dependency-groups]
# dev = [
# "pyaml>=25.1.0",
# "gradio>=5.16.1",
# ]
しかし、手動で pyproject.toml を作成するのは非常に面倒です。直接 .venv から抽出できないでしょうか？
後でエクスポートするのは良い習慣ではありません。pip freeze のように、最後にエクスポートする際の制限が大きく、多くの依存ライブラリをエクスポートして依存関係が読みにくくなります。
必要な具体的なサードパーティライブラリとそのバージョンを段階的に探求すべきです。依存ライブラリは書かなくても大丈夫です。
最後に、それを pyproject.toml に書き込み、uv lock、uv sync（オプション）、uv run を実行して、実行可能で互換性があることを確認します。
環境をロックした後に発生する可能性のある問題。 | .venv ディレクトリの変更 | パッケージ名の違い#
たとえば、__main__.py と requirements.txt がルートディレクトリにない場合、最初に作成した .venv は ./src/uiya にあります（ルートディレクトリに対して）。
そして、uv.lock は pyproject.toml を必要とし、pyproject.toml はルートディレクトリにある必要があります。その後、uv.lock は自動的に親フォルダ内の pyproject.toml を検索し、再度 .venv を作成します。
つまり、最初に私の .venv は ./src/uiya にあり、今は ./ に変わっています。
これは最初に私にいくつかの混乱をもたらしました。なぜなら、私は uv run を使用して子フォルダ内の .venv を使用できないことに気づいたからです。また、前述のように、uv は私に httpx[socks] をインストールできず、手動でインストールする必要がありました。
したがって、ここでの最良の方法は、最初から pyproject.toml を作成することです。そうすれば、uv run、uv pip install はすべてルートディレクトリ（pyproject.toml と同じディレクトリ）内の .venv を対象とします。
これは簡単な設定です：
name = "yutto-uiya"
version = "1.0.2"
description = ""
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
"gradio==5.16.1",
"pyaml==25.1.0",
"socksio==1.0.0",
"yutto",
]
authors = [{ name = "MrXnneHang", email = "[email protected]" }]
keywords = []
license = { text = "MIT" }
classifiers = [
"Operating System :: OS Independent",
"License :: OSI Approved :: MIT License",
"Typing :: Typed",
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: Implementation :: CPython",
]
[project.urls]
Homepage = "https://github.com/MrXnneHang/yutto-uiya"
Documentation = "https://github.com/MrXnneHang/yutto-uiya"
Repository = "https://github.com/MrXnneHang/yutto-uiya"
Issues = "https://github.com/MrXnneHang/yutto-uiya/issues"
[project.scripts]
uiya = "uiya.__main__:main"
[tool.uv.workspace]
members = ["packages/*"]
[tool.uv.sources]
yutto = { git = "https://github.com/MrXnneHang/yutto.git", rev = "depndency-adjust" }
[tool.pyright]
include = ["src/uiya", "tests"]
pythonVersion = "3.10"
typeCheckingMode = "strict"
[tool.hatch.build.targets.wheel]
packages = ["src/uiya"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
注意すべきは、依存関係やソースなどは手書きする必要がないことです。
これらは uv add gradio==5.16.1 を使用して追加できます。
また、GitHub リポジトリもサポートされています。たとえば：
uv add git+https://github.com/MrXnneHang/yutto.git@depndency-adjust
したがって、uv は実際には pyproject.toml と組み合わせて使用することを推奨しています。パッケージバージョンを管理したい場合、uv lock は pyproject.toml が存在する場合にのみ実行できます。
さらに、依存関係のほとんどは requirements から直接移行できますが、パッケージ名の違いに注意する必要があります。たとえば、socksio は pip での名前が httpx[socks] です。
しかし、一度 pyproject.toml と uv.lock が整備されれば、他の人が実行する際には uv run script を実行するだけで済みます。
さらに、ロックされたバージョンは他の人が環境のバージョン互換性の問題を考慮する必要がなく、あなたにとっても他の人にとっても親切です。
uv.lock を更新する必要がある場合は、最初に uv add packagename==version を実行し、その後に uv lock を実行する必要があります。
私は、ロックされたバージョンには余地を残さないことをお勧めします。また、uv lock の後は、手動でパッケージをインストールするために uv pip install を実行する必要はありません。直接 uv run script を実行すれば、uv.lock に基づいてパッケージが自動的に構成されます。あなたがそれを実行できれば、他の人も同様に実行できるでしょう。もちろん、Windows と Linux の間で win32api を使用しているものは除きます。
システム間の互換性を考慮するために、システム依存の低レベル API の使用は避けるべきです。
実際、この段階で uv はほぼ卒業しています。なぜ突然自信を持っているのかというと、私は実際に実践を通じて、元々構造が混乱していたプロジェクトを整理し、GitHub から直接インストールできる形式にパッケージ化しました。
https://github.com/MrXnneHang/yutto-uiya
重要なのは pyproject.toml と uv.lock です。uv.lock は pyproject.toml に基づいて自動生成されます。
実際に手を動かすことは、ただ見るよりもずっと早いです。そして理解が突然深まります。なぜなら、さまざまな問題に直面するからです。宿題を写す過程は非常に苦痛ですが、写し終えた後は非常に快適です。
ちなみに、私が写したのは：
https://github.com/yutto-dev/yutto
uv スクリプトの実行。#
実行可能ファイル#
前述のように、uv run pip、uv run python などを使用して bin 内の内容を実行できます。
ここでは詳しく説明しません。
Python スクリプト。#
ここでは、pyproject.toml がある場合とない場合の 2 つの状況に分けます。
pyproject.toml + uv.lock がある場合#
この場合、実際には uv.lock の内容に基づいて実行されます。uv.lock と同じディレクトリに自動的に .venv が作成され、その .venv 内で環境が自動的に構成され、実行されます。
したがって、このモードは一般的に次のようになります：
スクリプトを実行する：
git clone XXX
uv run XXX
何も気にする必要はありません。もし動かなければ、それは絶対に私の問題ではなく、メンテナの問題です。
もしメンテナが言うなら、一般的には次のようになります：
uv add package==version
uv lock
uv run XXX # 成功した場合はアップロードし、そうでない場合はパッケージのバージョンを調整することを検討します
最終的にデバッグが成功した場合、あなたが良い人であれば、uv.lock を一緒にアップロードし、ユーザーに直接 uv run XXX を実行できると言うでしょう。
なぜなら、大部分の人々は本当に uv の使い方がわからないからです。彼らは requirements.txt を探し回り、見つからず、しばらくの間 uv pip install uv.lock を試みます...
そして、どうしても uv run pip と uv pip の違いがわからないのです。私も以前はそうでしたし、心理的な影を抱えていました。
pyproject.toml + uv.lock がない場合#
この場合は、実際には pip を uv pip に置き換えて加速するのと似ています。
実際、私は現在 pyproject.toml + uv.lock を使用して管理することをよりお勧めします。
しかし、あなたは依然として requirements.txt を使用することができます。
この場合、.venv を考慮する必要はなく、conda 内で uv と環境をインストールするだけで大丈夫です。
原理：もしあなたが conda 環境をアクティブにしているなら、uv pip install などもデフォルトで conda 環境にインストールされます。
もちろん、もし独立した .venv が必要な場合は、次のような方法を考慮することもできます：
conda activate 11 # Python 3.11 の基本環境
uv venv --seed -p 3.11
conda deactivate # 前述のように、環境を退出しないと conda にインストールされます。
uv pip install -r requirements.txt
この場合、あなたの .venv は独立したものになります。しかし、制限があります。つまり、現在のディレクトリに作成され、そこにアクセスする必要があるようです。uv run XXX を実行する場合。
それは、pyproject.toml + uv.lock の場合のように、.venv がルートディレクトリにあっても、プロジェクトディレクトリのどこからでもアクセスできるわけではありません。
したがって、私は個人的に pyproject.toml + uv.lock の形式と、conda + uv を使用して conda + pip を置き換えることをお勧めします。
プロジェクトをパッケージ化した後、どのように繰り返しコンパイルしますか？#
最初に私が実行していた方法は：
uv run __main__.py
これは開発段階に適しており、繰り返しデバッグできます。
その後、コンパイルデバッグ段階に入ります。つまり、実行可能ファイルを直接実行したいのです。ここでの名前は uiya です。
私のやり方は非常に愚かで、GitHub にアップロードし、次のようにします：
conda create -n test-uiya python=3.10
conda activate test-uiya
uv pip install git+https://github.com/MrXnneHang/yutto-uiya.git@gradio-webui
その後、コードを更新するたびに、再度 uv pip install を実行します。幸いなことに、最新のブランチを検出し、キャッシュの影響を受けずにアンインストールする必要はありません。
それは確かに成功しました。最初に成功して実行できたとき、私は非常に興奮しました。
しかし、その後、この方法は非常に疲れました。
なぜなら、毎回コードを GitHub にアップロードし、再度インストールする必要があるからです。このプロセスは非常に面倒です。
私は一行のコードで自動的に更新できることを望んでいました。
ここで、ローカルコンパイルと更新について言及する必要があります。上記の方法を遠隔コンパイルと呼びましょう。=-=。
ローカルでコンパイルして実行可能プログラムを生成する。#
ええと、どう言えばいいのでしょうか？
特に指示は必要ないようです。
万能の uv run。
あなたはただ uv run uiya を実行すれば大丈夫です。
それは最新のコードに基づいて実行されます。なぜなら、この時点では実際にはコンパイルされていない状態であり、あなたは pyproject.toml に uiya = "uiya.__main__:main" を設定しているので、自動的にあなたの __main__.py を実行します。
`
特にコンパイルする必要はないようです。Vue のようにリアルタイムプレビューができるので、効率が高いです。コンパイルしてから確認するよりも高いです。
私が最初から疑問に思っていた uv sync#
私はそれが私たちのパッケージ管理において重要な役割を果たすと思っていましたが、実際には使わなくても大丈夫なようです。
sync の翻訳は同期であり、環境を同期します。
おそらく uv lock の後に同期するのでしょうか？しかし、uv run は毎回 uv.lock の内容を確認すると思います。
ここでの使用例を見てみましょう：
ローカルでデバッグしたい場合、最良の実践は最新のソースコードを GitHub からダウンロードして実行することです。
git clone [email protected]:yutto-dev/yutto.git
cd yutto/
uv sync
uv run yutto -v
https://github.com/yutto-dev/yutto/blob/main/CONTRIBUTING.md
このことから、sync は環境をインストールするためのものであることが推測できますが、現在は直接 uv run yutto を実行できるようです。
つまり、uv sync は現在 uv run の手順に統合されているため、手動で uv sync を実行する必要はありません。
もちろん、時々奇妙な環境の問題に遭遇した場合は、uv sync を実行してみることができます。
以前の実験に従い、uv run によって生成された .venv と pyproject.toml および uv.lock は同じディレクトリにあります。
再度 uv sync をテストしてみましょう：
xnne@xnne-PC:~$ git clone [email protected]:MrXnneHang/yutto-uiya.git
正克隆到 'yutto-uiya'...
remote: Enumerating objects: 898, done.
remote: Counting objects: 100% (57/57), done.
remote: Compressing objects: 100% (39/39), done.
remote: Total 898 (delta 23), reused 36 (delta 12), pack-reused 841 (from 1)
接收对象中: 100% (898/898), 389.53 KiB | 429.00 KiB/s, 完成.
处理 delta 中: 100% (512/512), 完成.
xnne@xnne-PC:~$ cd yutto-uiya/
xnne@xnne-PC:~/yutto-uiya$ uv sync
Using CPython 3.13.0
Creating virtual environment at: .venv
Resolved 64 packages in 2ms
Built yutto-uiya @ file:///home/xnne/yutto-uiya
Prepared 1 package in 1.49s
xnne@xnne-PC:~/yutto-uiya$ ls .venv/
bin/ CACHEDIR.TAG .gitignore lib/ lib64/ pyvenv.cfg
ここで、確かにルートディレクトリの .venv に環境がインストールされていることがわかります。
推測は正しいです。
ただし、ここで奇妙な点があります。Python バージョンは、ソース内で最初に排除されるものをデフォルトで探します。Python バージョンを制御する必要がある場合は、前述の conda をアクティブにしてから退出する方法を参照してください。
もちろん、conda も必要ないようです。なぜなら、uv には独自のグローバルインタプリタがあり、指定されたバージョンがない場合は自動的にダウンロードして補充します。ただし、位置が少し奇妙です。
環境に問題がある場合は、.venv を削除してから再度 uv sync を実行してみてください。それでも問題が解決しない場合は、メンテナを探してください。=-=。
おめでとう、uv は卒業しました。
これは非常に長いように見えますが、私は 2 日間だけ書きました。大部分は無駄話です。
時間があれば、使い方のバージョンを整理するかもしれませんが、私は常に探索を重視し、整理を重視していません。
だから... 運命に任せます。