探索 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 は人間が読める 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 はプロジェクトの広範な要件を指定するために使用されるのに対し、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（バージョン指定なし）を使用した場合、私のユーザーは三ヶ月後のある日、特定の 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 をインストールする必要はありません。
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 の環境を管理し、必要なときにその環境を ./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 と 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"]
依存関係やソースなどは手書きする必要はありません。
これらは 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 がある場合とない場合の二つの状況に分けます。
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
推測するに、この 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 は卒業しました。
これは非常に長いようですが、私はたった二日間で書きました。大部分は無駄話です。
時間があれば、使い方のバージョンを整理するかもしれませんが、私は常に探索を重視し、整理を重視していません。
ですので... 運命に任せます。