はじめに
なんだか流行っていてしかも良いものらしい、ということでuv を試してみました。一人寂しい夏休みに自由課題です。おじさんは現在、poetry+pyenv でお仕事をしています。
offical pageの Getting started以下を読みつつ、みなさんの日本語記事を拝読し、ポチポチしたメモです。WSL2です。
確かにさくさく早い感じです。
内容
なんだかサクッと入りました。何かを入れるために既にインストールしたような気もします。Installationに書いてある通り下記を実行しました。
$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.8.9 x86_64-unknown-linux-gnu
no checksums to verify
installing to /home/xt/.local/bin
uv
uvx
everything's installed!
To add $HOME/.local/bin to your PATH, either restart your shell or run:
source $HOME/.local/bin/env (sh, bash, zsh)
source $HOME/.local/bin/env.fish (fish)
最初にuv とタイプしてみます。厳選されたコマンド?を見ることできます。
$ uv
An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
Commands:
run Run a command or script
init Create a new project
add Add dependencies to the project
remove Remove dependencies from the project
version Read or update the project's version
sync Update the project's environment
lock Update the project's lockfile
export Export the project's lockfile to an alternate format
tree Display the project's dependency tree
tool Run and install commands provided by Python packages
python Manage Python versions and installations
pip Manage Python packages with a pip-compatible interface
venv Create a virtual environment
build Build Python packages into source distributions and wheels
publish Upload distributions to an index
cache Manage uv's cache
self Manage the uv executable
help Display documentation for a command
(以下略)
python のインストール
下記で利用可能なpython が見えます。利用可能とはpython 実行ファイルへのリンクが書かれ、そうでないものは と表示されています。
$ uv python list
cpython-3.14.0rc1-linux-x86_64-gnu <download available>
cpython-3.14.0rc1+freethreaded-linux-x86_64-gnu <download available>
cpython-3.13.6-linux-x86_64-gnu <download available>
cpython-3.13.6+freethreaded-linux-x86_64-gnu <download available>
cpython-3.12.11-linux-x86_64-gnu <download available>
cpython-3.12.3-linux-x86_64-gnu /usr/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu /usr/bin/python3 -> python3.12
cpython-3.12.3-linux-x86_64-gnu .pyenv/shims/python3.12
cpython-3.12.3-linux-x86_64-gnu .pyenv/shims/python3
cpython-3.11.13-linux-x86_64-gnu <download available>
cpython-3.10.18-linux-x86_64-gnu <download available>
cpython-3.9.23-linux-x86_64-gnu <download available>
cpython-3.8.20-linux-x86_64-gnu <download available>
pypy-3.11.13-linux-x86_64-gnu <download available>
pypy-3.10.16-linux-x86_64-gnu <download available>
pypy-3.9.19-linux-x86_64-gnu <download available>
pypy-3.8.16-linux-x86_64-gnu <download available>
graalpy-3.11.0-linux-x86_64-gnu <download available>
graalpy-3.10.0-linux-x86_64-gnu <download available>
graalpy-3.8.5-linux-x86_64-gnu <download available>
実はこの環境で私は現在pyenv を使っているのですが、それらは参照されませんでした。独立しているのかな。
$ pyenv versions
* system (set by /home/xt/.pyenv/version)
3.10.17
3.12.3
最新のpython を入れてみました。自分の~/.local/share/uv/python/ 以下にダウンロードされたようです。
$ uv python install
Installed Python 3.13.6 in 7.61s
+ cpython-3.13.6-linux-x86_64-gnu (python3.13)
$ uv python list
cpython-3.14.0rc1-linux-x86_64-gnu <download available>
cpython-3.14.0rc1+freethreaded-linux-x86_64-gnu <download available>
cpython-3.13.6-linux-x86_64-gnu .local/bin/python3.13 -> .local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/bin/python3.13
cpython-3.13.6-linux-x86_64-gnu .local/share/uv/python/cpython-3.13.6-linux-x86_64-gnu/bin/python3.13
cpython-3.13.6+freethreaded-linux-x86_64-gnu <download available>
cpython-3.12.11-linux-x86_64-gnu <download available>
cpython-3.12.3-linux-x86_64-gnu /usr/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu /usr/bin/python3 -> python3.12
cpython-3.12.3-linux-x86_64-gnu .pyenv/shims/python3.12
cpython-3.12.3-linux-x86_64-gnu .pyenv/shims/python3
今までpyenv を参照していましたが、デフォルトに指定されました。これまでpython local で指定したものが使えるのか不安ですが。。。
以下、uv python install 実行直後は、python3.13 が~/.loca.bin/にインストールされるが、python3 としては、~/.pyenv/shims/が参照されています。これは、bashrc に書いている環境変数の設定によるのかな。。
$ python3 -V
Python 3.12.3
$ which python3.13
/home/xt/.local/bin/python3.13
$ which python3
/home/xt/.pyenv/shims/python3
使用するpython version の指定(以前はpyenv)
使うversion を固定するには uv python pin 3.11のようにできます。これを使うのが正しいようです。
$ uv python pin 3.13
Pinned `.python-version` to `3.13`
$ ls -la
total 12
drwxr-xr-x 2 xk xt 4096 Aug 31 14:12 .
drwxr-xr-x 28 xk xt 4096 Aug 31 14:10 ..
-rw-r--r-- 1 xk xt 5 Aug 31 14:12 .python-version
$ cat .python-version
3.13
デフォルトでpython3.13 を利用するようにしてみました。この --default は実験的な段階だそうでした。使わない方が良いかも。。。
$ uv python install --default
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.6 in 60ms
+ cpython-3.13.6-linux-x86_64-gnu (python, python3)
$ which python3.13
/home/xt/.local/bin/python3.13
$ python -V
Python 3.13.6
$ which python
/home/xt/.local/bin/python
仮想環境 uv venv
とりあえず仮想環境を作れる。ディレクトリ .vnev が作られ、それこにあるスクリプト activate を source コマンドで読んで反映させます。python -m venv で実行しているいつもの手順。
$ uv venv
Using CPython 3.13.6
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
$ source .venv/bin/activate
(my_venv) $ which python
/home/xt/uv_test/.venv/bin/python
実行 uv run
実行するには uv run example.pyで実行できるのだが、標準入力も受け付ける。これは便利かも。（pythonでもあったのかな？）
$ echo 'print("hello world!")' | uv run -
hello world!
$ uv run - <<EOF
print("hello world!")
EOF
hello world!
ツールを使う Ruffとか
インストールしてくれます。。python に依存しているのかな。よく分からん。
$ uvx ruff
Installed 1 package in 22ms
Ruff: An extremely fast Python linter and code formatter.
Usage: ruff [OPTIONS] <COMMAND>
Commands:
check Run Ruff on the given files or directories
rule Explain a rule (or all rules)
config List or describe the available configuration options
linter List all supported upstream linters
（略）
$ which ruff
$ uvx ruff --version
ruff 0.12.8
あくまでこの環境でしか使えない。OS全体に入れているわけではない。
uvx ruffは uv tool run ruffと等価とのこと。
下記の注意がありました。仮想環境と自分のプロジェクトでpytest が違うので注意しよう。
If you are running a tool in a project and the tool requires that your project is installed, e.g., when using pytest or mypy, you'll want to use uv run instead of uvx. Otherwise, the tool will be run in a virtual environment that is isolated from your project.
If your project has a flat structure, e.g., instead of using a src directory for modules, the project itself does not need to be installed and uvx is fine. In this case, using uv run is only beneficial if you want to pin the version of the tool in the project's dependencies.
Project で使う。
これをなぞるだけ。だけ。なのだが、、、
定義をpyproject.toml に書いてくれるらしい。poetry のときと同じだ。
ここにpyproject.toml のオフィシャルページがあるとのこと。知らなかった。
実は、一緒に .python-version と .git が作られている。確かに、いつも pyenv でpython version をlocal に指定していたし、git repostiory で管理していたけれど、最初から用意してくれるらしい。
$ ls -la
total 28
drwxr-xr-x 3 xt xt 4096 Aug 12 14:55 .
drwxr-xr-x 3 xt xt 4096 Aug 12 14:55 ..
drwxr-xr-x 7 xt xt 4096 Aug 12 14:55 .git
-rw-r--r-- 1 xt xt 109 Aug 12 14:55 .gitignore
-rw-r--r-- 1 xt xt 5 Aug 12 14:55 .python-version
-rw-r--r-- 1 xt xt 0 Aug 12 14:55 README.md
-rw-r--r-- 1 xt xt 89 Aug 12 14:55 main.py
-rw-r--r-- 1 xt xt 157 Aug 12 14:55 pyproject.toml
$ ls .git
HEAD branches config description hooks info objects refs
$ git status
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.gitignore
.python-version
README.md
main.py
pyproject.toml
nothing added to commit but untracked files present (use "git add" to track)
Project で自分のコードをパッケージとしてインストールする
とりあえず下記でできたのだが、良いのか分からない。poetry では packages=["./src"] と書いていたのだが、の意味をよく理解しないで使っていました。今回、少し違って、
- src 以下をパッケージとして、pyproject.toml の[tool.setuptools.packages.find] で指定する
- uv でインストールする。
としました。なんだか解ではない気もするのだが動いたのでメモしておきます。
[tool.setuptools.packages.find]
where = ["src"]
仮想環境にインストールします。
uv pip install -e .
これで動きました。
$ tree
.
├── README.md
├── __init__.py
├── main.py
├── pyproject.toml
├── src
│ ├── __pycache__
│ │ └── hoge.cpython-313.pyc
│ ├── hello_world.egg-info
│ │ ├── PKG-INFO
│ │ ├── SOURCES.txt
│ │ ├── dependency_links.txt
│ │ ├── requires.txt
│ │ └── top_level.txt
│ └── hoge.py
└── uv.lock
4 directories, 12 files
$ cat src/hoge.py
print("hogehoge")
$ cat main.py
import hoge
def main():
print("Hello from hello-world!")
if __name__ == "__main__":
main()
$ uv run main.py
hogehoge
Hello from hello-world!
既存のプロジェクトからの移行
下記の情報を参考にしたいです。poetry でpyproject.toml がある場合は uv sync だけでよいそうですが、~~後で確認します。~~実は、そうでもありませんでした。
実際に自分のとある一年前に更新したままのコードで実行してみると、、、
$ uv sync
error: No `project` table found in: `/home/xt/torupa/study_autoencoder/pyproject.toml`
と言われてしまいました。確かにpyproject.toml に [project] というはありませんでした。みてみると、tools.poetry で始まるものがたくさん書いてありました。以下は冒頭部分。
[tool.poetry]
name = "study-autoencoder"
version = "0.1.0"
description = "Implementation of auto encoder"
authors = ["torupa"]
license = "MIT"
readme = "README.md"
packages = [
{ include = "models", from = "." },
]
(以下略)
tool.poetry の内容を projects として再度uv sync すると、またしてもエラー。
$ uv sync
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.12`.
× Failed to build `study-autoencoder @ file:///home/xt/torupati/study_autoencoder`
├─▶ The build backend returned an error
╰─▶ Call to `poetry.core.masonry.api.prepare_metadata_for_build_editable` failed (exit status: 1)
[stderr]
Traceback (most recent call last):
File "<string>", line 14, in <module>
File "/home/xt/.cache/uv/builds-v0/.tmpaRJ4bv/lib/python3.12/site-packages/poetry/core/masonry/api.py", line 42, in
prepare_metadata_for_build_wheel
poetry = Factory().create_poetry(Path().resolve(), with_groups=False)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/xt/.cache/uv/builds-v0/.tmpaRJ4bv/lib/python3.12/site-packages/poetry/core/factory.py", line 60, in
create_poetry
raise RuntimeError("The Poetry configuration is invalid:\n" + message)
RuntimeError: The Poetry configuration is invalid:
- project.authors[0] must be object
hint: This usually indicates a problem with the package or the build environment.
- [project] に各author の書式が違うので直した。
- uv sync を実行するとtorchvision に関係して cuda のモジュールをたくさんインストールしようとしたので、下記を上の方にもってきた。
[[tool.poetry.source]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
priority = "explicit"
それでも治らない。
- packages=[...] が問題なったので削除した。パッケージ名がプロジェクト名と一致しなければいけないので、ディレクトリを作った。
などとしましたが、uv sync で移行はできませんでした。（涙）
とにかく、簡単にいかない人がここに一人いました。ということで、この件については作り直しました。
pytest 導入
poetry では poetry add --group dev pytest としてたが、こちらでは、pyyproject.toml で
[project.optional-dependencies]
dev = ["pytest"]
と書いて、インストールしました。
$ uv pip install -e .[dev]
Resolved 16 packages in 83ms
Built study-autoencoder @ file:///home/xt/torupati/s
Prepared 1 package in 684ms
Uninstalled 1 package in 0.93ms
Installed 6 packages in 12ms
+ iniconfig==2.1.0
+ packaging==25.0
+ pluggy==1.6.0
+ pygments==2.19.2
+ pytest==8.4.1
~ study-autoencoder==0.1.0 (from file:///home/xt/torupati/study_autoencoder)
おわりに
これでこれまでのpetry から uv に移行していこうと思います。アップデートしたいpoetry でのproject があるので uv に移してみようかな。
- pyproject.toml に書く packages の件。
- test、lintのベストプロくてぃす
- Docker
が次にやりたいことかな。
お盆休み、何をやっているのか。。。仕事に役に立つかな。おじさん。
(2025/8/12)
メモ