Poetry・asdfの使い方｜違い・組み合わせ方とエラーの直し方

2つのツールは受け持つ範囲が違います。asdf が python の版を決め、Poetry がその Python で仮想環境を作って依存を入れます。

flowchart TD
    T[.tool-versions<br>python 3.12.3] --> A[asdf の shim が<br>Python の版を決める]
    A --> P[Poetry がその Python で<br>仮想環境を作る]
    Y[pyproject.toml<br>poetry.lock] --> P
    P --> V[仮想環境に<br>依存パッケージ]

よく使う操作を先にまとめます。

やりたいこと	コマンド	ツール
プロジェクトを作る	poetry new myapp	Poetry
パッケージを追加する	poetry add requests	Poetry
lock どおりに入れる	poetry install	Poetry
仮想環境の中で実行する	poetry run python app.py	Poetry
Python を入れる	asdf install python 3.13.7	asdf
このフォルダの版を決める	asdf set python 3.12.3	asdf
いつも使う版を決める	asdf set -u python 3.13.7	asdf
今の版を確かめる	asdf current	asdf

確認環境：Ubuntu 24.04・Poetry 2.5.1（poetry-core 2.5.0、pipx 1.18.4 で導入）・asdf 0.20.2（GitHub リリースのバイナリ）・asdf-python プラグイン（python-build 2.8.11）。asdf で Python 3.13.7 と 3.12.3 をソースからビルドし、Poetry のプロジェクト作成・依存の追加・lock・実行・ビルド・エラーの再現、asdf の切り替え・エラーの再現を bash で実際に動かした出力を載せています。Python のソースは Ubuntu のアーカイブにある配布物を使い、python-build の定義ファイルの SHA-256 と一致することを確かめました。Windows・Mac の手順、mise・uv の仕様は各公式ドキュメントで確かめました（確認日 2026年10月22日）。

Poetryとasdfの違い

Poetry は「このプロジェクトが使うライブラリ」を、asdf は「この PC で使う言語の版」を管理します。 名前が並べて検索されやすい2つですが、競合するツールではなく、重ねて使う関係です。

観点	Poetry	asdf
一言でいうと	Python の依存管理・パッケージングツール	複数言語に対応したバージョン管理ツール
対象の言語	Python だけ	プラグインで 845 種（asdf plugin list all の件数）
設定ファイル	pyproject.toml・poetry.lock	.tool-versions
仮想環境	作る（プロジェクトごと）	作らない
Python 本体	原則入れない（2.1 から実験的な poetry python install がある）	入れる（asdf-python はソースからビルド）
実体	Python 製の CLI	Go 製の1つの実行ファイル（0.16.0 から）

Poetry の公式ドキュメントには「Poetry は Python のインタープリターを入れない（Poetry will not install a Python interpreter for you）」とあります。そのため、Python の版を asdf や pyenv で用意し、依存を Poetry で管理する組み合わせが、よく使われる形です。

Poetryとは

Poetry（ポエトリー）は、Python のプロジェクトの依存関係・仮想環境・パッケージの作成をまとめて行うツールです。 pip と venv と requirements.txt で手作業していたことを、コマンドと2つのファイルで管理します。

pip だけの場合と比べると、次のように対応します。

やりたいこと	pip + venv	Poetry
仮想環境を作る	python -m venv .venv	自動（最初の add・install で作る）
パッケージを追加する	pip install requests のあと pip freeze	poetry add requests
依存を書くファイル	requirements.txt（手で管理）	pyproject.toml（自動で追記）
正確な版を固定する	pip freeze > requirements.txt	poetry.lock（自動）
開発用だけ分ける	requirements-dev.txt など別ファイル	poetry add --group dev pytest
他の人が同じ環境を作る	pip install -r requirements.txt	poetry install

関連記事「pipコマンド一覧｜installのバージョン指定とrequirements.txt」で扱っています。

Poetry 2.x で変わったこと

2025年1月に出た Poetry 2.0 から、1.x の書き方と違う点がいくつかあります。検索で見つけたコマンドが動かないときは、まずここを確かめます。

1.x の書き方	2.x（2.5.1 で確認）
[tool.poetry.dependencies] に依存を書く	[project] の dependencies に書く（旧形式も使える）
poetry add --group dev は [tool.poetry.group.dev.dependencies]	[dependency-groups]（PEP 735）に書かれた
poetry shell	本体から外れた。poetry env activate かプラグイン
poetry export	本体から外れた。poetry-plugin-export を入れる
poetry install --sync	poetry sync（--sync は非推奨）
poetry add --dev	poetry add --group dev（-D は今も使える）
仮想環境は Poetry を入れた Python で作る	今 python で動く Python で作る（virtualenvs.use-poetry-python が既定で false）

Poetryのインストール（pipx・公式インストーラー）

公式ドキュメントが最初に挙げる方法は pipx です。 Poetry は Python 3.10 以上で動きます。どの方法でも、Poetry はプロジェクトとは別の専用の仮想環境に入ります。

方法	コマンド	更新・削除
pipx（推奨）	pipx install poetry	pipx upgrade poetry・pipx uninstall poetry
公式インストーラー（Linux・Mac・WSL）	curl -sSL https://install.python-poetry.org | python3 -	poetry self update・同じコマンドに --uninstall
公式インストーラー（Windows PowerShell）	(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -	インストーラーの再実行
CI	pipx install poetry==2.5.1 のように版を固定	―

公式ドキュメントは、Windows では poetry self update が不安定なことがあるため、インストーラーを再実行する方法を勧めています。Microsoft Store の Python を使っている場合は、py を python に置き換えます。

pipx で入れる

pipx で入れたときの出力です。最後の行で、poetry コマンドが使えるようになったことが分かります。

$ pipx --version
1.18.4
$ pipx install poetry
creating virtual environment...
installing poetry...
  installed package poetry 2.5.1, installed using Python 3.11.15
  These apps are now available
    - poetry
done! ✨ 🌟 ✨
$ poetry --version
Poetry (version 2.5.1)
$ poetry about
Poetry - Package Management for Python

Version: 2.5.1
Poetry-Core Version: 2.5.0

~/.local/bin が PATH に入っていないと、インストールの途中で次の注意が出て、poetry は見つかりません。pipx ensurepath で PATH に足し、端末を開き直します。

⚠️  Note: '/home/user/.local/bin' is not on your PATH environment
    variable. These apps will not be globally accessible until your PATH is
    updated. Run `pipx ensurepath` to automatically add it, or manually modify
    your PATH in your shell's config file (e.g. ~/.bashrc).
done! ✨ 🌟 ✨
$ poetry --version
bash: poetry: command not found
$ pipx ensurepath
Success! Added /home/user/.local/bin to the PATH environment variable.
$ tail -2 ~/.bashrc
# Created by `pipx` on 2026-10-22 07:41:23
export PATH="$PATH:/home/user/.local/bin"

Poetry 本体が入った仮想環境は 66MB でした。公式インストーラーの場合、本体は Linux で ~/.local/share/pypoetry、Mac で ~/Library/Application Support/pypoetry、Windows で %APPDATA%\pypoetry に入り、poetry コマンドは ~/.local/bin（Windows は %APPDATA%\Python\Scripts）に置かれます。

タブ補完を有効にする

公式ドキュメントのコマンドです。設定後にシェルを開き直します。

# bash
poetry completions bash >> ~/.bash_completion

# zsh（~/.zshrc に fpath+=~/.zfunc と autoload -Uz compinit && compinit も足す）
poetry completions zsh > ~/.zfunc/_poetry

# Oh My Zsh（~/.zshrc の plugins に poetry を足す）
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

# fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Poetryの使い方：プロジェクト作成から実行まで

基本の流れは「new（または init）→ add → install → run」の4つです。 1つずつ実際の出力で見ていきます。

poetry new でプロジェクトを作る

$ poetry new hello-poetry
Created package hello_poetry in hello-poetry
$ cd hello-poetry
$ find . -type f | sort
./README.md
./pyproject.toml
./src/hello_poetry/__init__.py
./tests/__init__.py

作られた pyproject.toml です。Poetry 2.x では、名前や依存は標準の [project] に書かれます。requires-python には、Poetry を動かした Python（3.11.15）から >=3.11 が入りました。

[project]
name = "hello-poetry"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
]

[tool.poetry]
packages = [{include = "hello_poetry", from = "src"}]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

既存のフォルダで使うときは poetry init です。質問に答えながら pyproject.toml を作ります。-n を付けると質問を飛ばし、--name・--python などの値で作ります。

cd my-existing-app
poetry init                                   # 対話で作る
poetry init -n --name my-app --python '>=3.12'  # 質問なしで作る

公式ドキュメントでは、poetry new は既定で src レイアウトになり、--flat を付けるとフォルダの直下にパッケージを置く形になります。

poetry add でパッケージを追加する

$ poetry add requests
Creating virtualenv hello-poetry-wfzNIG1A-py3.11 in /home/user/.cache/pypoetry/virtualenvs
Using version ^2.34.2 for requests

Updating dependencies
Resolving dependencies...

Package operations: 5 installs, 0 updates, 0 removals

  - Installing certifi (2026.10.19)
  - Installing charset-normalizer (3.5.2)
  - Installing idna (3.20)
  - Installing urllib3 (2.8.0)
  - Installing requests (2.34.2)

Writing lock file

最初の add で仮想環境が作られ、requests とその依存の4つが入り、poetry.lock が書かれました。かかった時間は約6秒です。pyproject.toml には次の1行が足されます。

dependencies = [
    "requests (>=2.34.2,<3.0.0)"
]

出力の ^2.34.2（キャレット）は「2.34.2 以上、次のメジャー版 3.0.0 未満」という意味で、ファイルには範囲の形で書かれます。

依存の木は poetry show --tree で見られます。

$ poetry show --tree
requests 2.34.2 Python HTTP for Humans.
├── certifi >=2023.5.7
├── charset-normalizer >=2,<4
├── idna >=2.5,<4
└── urllib3 >=1.26,<3

開発用のパッケージを分ける（--group dev）

テストやリンターのように、本番では使わないものはグループに分けます。

$ poetry add --group dev pytest
Using version ^9.1.1 for pytest

Updating dependencies
Resolving dependencies...

Package operations: 5 installs, 0 updates, 0 removals

  - Installing iniconfig (2.3.1)
  - Installing packaging (26.3)
  - Installing pluggy (1.7.0)
  - Installing pygments (2.21.0)
  - Installing pytest (9.1.1)

Writing lock file

Poetry 2.5.1 では、[tool.poetry.group.dev.dependencies] ではなく、PEP 735 の [dependency-groups] に書かれました。 1.x の解説と見た目が違いますが、どちらの形も読まれます。

[dependency-groups]
dev = [
    "pytest (>=9.1.1,<10.0.0)"
]

グループを入れる・外すときは次のオプションを使います（公式ドキュメントより）。

コマンド	意味
poetry install	任意（optional）でないグループをすべて入れる
poetry install --without dev	dev を除いて入れる（本番用）
poetry install --with docs	任意のグループ docs も入れる
poetry install --only dev	dev だけ入れる
poetry install --all-groups	すべてのグループを入れる

版の指定のしかた

poetry add に渡す版の書き方です。--dry-run で、実際にどの版が選ばれるかを確かめました（2026年10月22日時点の humanize の最新は 4.16.0）。

書き方	意味	選ばれた版
poetry add humanize	最新を入れ、^ で範囲を書く	4.16.0（>=4.16.0,<5.0.0）
poetry add humanize@4.10.0	その版に固定	4.10.0
poetry add 'humanize@~4.10'	4.10.x の範囲（マイナー版は上げない）	4.10.0
poetry add 'humanize>=4.10,<4.12'	範囲を直接書く	4.11.0
poetry add humanize@latest	今の指定を最新に書き換える	4.16.0
poetry add 'git+https://github.com/python-humanize/humanize.git#4.16.0'	Git のタグやブランチから入れる	4.16.0（コミット 3c577d7）

> や < を含む指定は、シェルに解釈されないように引用符で囲みます。

poetry run と仮想環境の有効化

poetry run を付けると、仮想環境の Python で実行されます。

$ poetry run python -c 'import requests, sys; print(sys.executable)'
/home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.11/bin/python
$ poetry run pytest -q
.                                                                        [100%]
1 passed in 0.13s

毎回 poetry run を付けたくないときは、仮想環境を有効にします。poetry env activate は有効化のコマンドを「表示する」だけなので、eval で実行します。

$ poetry env activate
source /home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.11/bin/activate
$ eval "$(poetry env activate)"
$ which python
/home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.11/bin/python
$ deactivate

PowerShell では Invoke-Expression (poetry env activate) です。1.x の poetry shell は、2.x では次のメッセージで止まります。

$ poetry shell

Looks like you're trying to use a Poetry command that is not available.

Since Poetry (2.0.0), the shell command is not installed by default. You can use,

  - the new env activate command (recommended); or
  - the shell plugin to install the shell command

Documentation: https://python-poetry.org/docs/managing-environments/#activating-the-environment

Note that the env activate command is not a direct replacement for shell command.

poetry shell を使い続けたいときは、プラグインの poetry-plugin-shell（2026年10月22日時点で 1.0.1）を入れます。

コマンドを登録して実行する（[project.scripts]）

pyproject.toml に [project.scripts] を書くと、自分のパッケージの関数をコマンドとして呼べます。

[project.scripts]
hello = "hello_poetry:main"

import sys
import requests


def main() -> None:
    print("Python", sys.version.split()[0])
    print("requests", requests.__version__)

書いただけでは登録されません。poetry install でプロジェクト自身を入れ直すと使えるようになります。

$ poetry run hello
Command not found: hello
$ poetry install
Installing dependencies from lock file

No dependencies to install or update

Installing the current project: hello-poetry (0.1.0)
$ poetry run hello
Python 3.11.15
requests 2.34.2

pyproject.tomlとpoetry.lockの中身

pyproject.toml は「使いたい範囲」を人が書くファイル、poetry.lock は「実際に決まった版」を Poetry が書くファイルです。 どちらも Git にコミットします。

flowchart TD
    A[poetry add] --> B[pyproject.toml<br>範囲を書く]
    B --> C[依存を解決]
    C --> D[poetry.lock<br>正確な版とハッシュ]
    D --> E[poetry install<br>lock どおりに入れる]

pyproject.toml の主な項目

Poetry 2.x で使う項目です。[project] は Python 標準（PEP 621）の書き方で、Poetry 以外のツールも読みます。

場所	項目	意味
[project]	name・version	パッケージ名と版（パッケージモードでは必須）
[project]	description・readme・license	説明・README のファイル・ライセンス
[project]	authors・maintainers	作者と保守担当（名前とメール）
[project]	requires-python	対応する Python の版の範囲
[project]	dependencies	本番で使う依存
[project.urls]	homepage・repository・documentation	関連 URL
[project.scripts]	コマンド名 = "モジュール:関数"	コマンドの登録
[dependency-groups]	dev = [...]	開発用などのグループ
[tool.poetry]	package-mode・packages	パッケージにするか・含めるフォルダ
[tool.poetry]	requires-poetry	このプロジェクトで使える Poetry の版
[build-system]	requires・build-backend	ビルドに使う poetry-core

pytest・Black・isort・Ruff など多くのツールは、設定も pyproject.toml の [tool.ツール名] に書けます。1つのファイルにまとめると、設定の置き場所が散らばりません。

[tool.pytest.ini_options]
addopts = "-q"
testpaths = ["tests"]

[tool.black]
line-length = 100

[tool.isort]
profile = "black"

[tool.pytest.ini_options] を足したあと、poetry run pytest は -q を付けなくても短い表示になり、poetry check も通りました。

$ poetry run pytest
.                                                                        [100%]
1 passed in 0.14s
$ poetry check
All set!

poetry.lock の中身

poetry.lock の先頭です。パッケージごとに、版・対応する Python・グループ・配布ファイルのハッシュが書かれます。requests と pytest を入れた状態で、パッケージは11件、ファイルは 35,565 バイトでした。

# This file is automatically @generated by Poetry 2.5.1 and should not be changed by hand.

[[package]]
name = "certifi"
version = "2026.10.19"
description = "Python package for providing Mozilla's CA Bundle."
optional = false
python-versions = ">=3.7"
groups = ["main"]
files = [
    {file = "certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b"},
    {file = "certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae"},
]

1行目のとおり、手で書き換えるファイルではありません。公式ドキュメントは、アプリケーションでは lock ファイルをコミットするよう勧めています（ライブラリは利用者側が lock を使わないため、コミットしない選択もあると説明しています）。

lock ファイルとずれたとき

pyproject.toml を手で書き換えて poetry.lock を更新しないまま poetry install すると、次のエラーで止まります。poetry lock で lock を作り直すと入りました。

$ poetry install
Installing dependencies from lock file

pyproject.toml changed significantly since poetry.lock was last generated. Run `poetry lock` to fix the lock file.
$ poetry lock
Resolving dependencies...

Writing lock file
$ poetry install
Installing dependencies from lock file

Package operations: 1 install, 0 updates, 0 removals

  - Installing humanize (4.16.0)

Poetryの仮想環境（場所・Pythonの版）

Poetry の仮想環境は、既定ではプロジェクトの外（キャッシュのフォルダの下の virtualenvs）にできます。 場所と使っている Python は poetry env info で分かります。

$ poetry env info

Virtualenv
Python:         3.11.15
Implementation: CPython
Path:           /home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.11
Executable:     /home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.11/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.11.15
Path:       /usr
Executable: /usr/bin/python3.11

OS	仮想環境の既定の場所
Linux	~/.cache/pypoetry/virtualenvs
Mac	~/Library/Caches/pypoetry/virtualenvs
Windows	C:\Users\<ユーザー名>\AppData\Local\pypoetry\Cache\virtualenvs

プロジェクトの中に .venv を作る（in-project）

VS Code などのエディターに仮想環境を見つけさせやすいように、プロジェクトの直下の .venv に作る設定です。--local を付けると、そのプロジェクトの poetry.toml に書かれます。

$ poetry config virtualenvs.in-project true --local
$ cat poetry.toml
[virtualenvs]
in-project = true
$ poetry install
Creating virtualenv new-py in /home/user/work/new-py/.venv
$ ls -a
.  ..  .venv  poetry.lock  poetry.toml  pyproject.toml

--local を付けないと、ユーザー全体の設定ファイル（Linux は ~/.config/pypoetry/config.toml）に書かれます。設定は環境変数でも渡せて、virtualenvs.in-project は POETRY_VIRTUALENVS_IN_PROJECT になります。優先順位は「環境変数 → poetry.toml → config.toml → 既定値」です。すでにある仮想環境は移動しないので、設定を変えたら poetry env remove --all で消して作り直します。

Python の版を選ぶ（poetry env use）

poetry env use で、そのプロジェクトの仮想環境を別の Python で作ります。

$ poetry env use python3.13
Creating virtualenv hello-poetry-wfzNIG1A-py3.13 in /home/user/.cache/pypoetry/virtualenvs
Using virtualenv: /home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.13
$ poetry env list
hello-poetry-wfzNIG1A-py3.11
hello-poetry-wfzNIG1A-py3.13 (Activated)
$ poetry run python --version
Python 3.13.13
$ poetry env remove python3.13
Deleted virtualenv: /home/user/.cache/pypoetry/virtualenvs/hello-poetry-wfzNIG1A-py3.13

1つのプロジェクトに、Python の版ごとの仮想環境を複数持てます。 poetry env use には python3.13 のようなコマンド名、3.13 のような版、フルパスを渡せます。system を渡すと既定の動きに戻ります。

requires-python に合わない Python で動かすと、Poetry は合う版を PATH から探します。>=3.12 のプロジェクトを、PATH の python が 3.11 の状態で入れた出力です。

$ poetry install
The currently activated Python version 3.11.15 is not supported by the project (>=3.12).
Trying to find and use a compatible version. 
Using python3.13 (3.13.13)
Creating virtualenv new-py-EBTdLNPk-py3.13 in /home/user/.cache/pypoetry/virtualenvs

Poetry で Python を入れる（poetry python install）

Poetry 2.1.0 から、Python Standalone Builds（ビルド済みの Python）を入れる poetry python コマンドが加わりました。公式ドキュメントでは実験的な機能（experimental）です。

$ poetry python install 3.12
Downloading and installing 3.12 (cpython) ... Done
Testing 3.12 (cpython) ... Done
$ poetry python list --managed
 Version Implementation Manager Path
 3.12.15 CPython        Poetry  /home/user/.local/share/pypoetry/python/cpython@3.12.15/bin/python3.12
$ poetry python remove 3.12.15
Removing installation 3.12.15 (cpython) ... Done

入れるのにかかった時間は約7秒でした。消すときは 3.12.15 のように X.Y.Z の形で指定します（3.12 だけだと Invalid Python version requested 3.12 で止まります）。

依存の更新・削除・同期（update・remove・sync）

poetry update は pyproject.toml の範囲の中でだけ版を上げます。 範囲を超えて上げたいときは、poetry add パッケージ@latest で範囲ごと書き換えます。

$ poetry add humanize@4.10.0
  - Installing humanize (4.10.0)
$ poetry show --outdated
humanize 4.10.0 4.16.0 Python humanize utilities
$ poetry update humanize
Updating dependencies
Resolving dependencies...

No dependencies to install or update
$ poetry add humanize@latest
Using version ^4.16.0 for humanize

  - Updating humanize (4.10.0 -> 4.16.0)
$ poetry remove humanize
  - Removing humanize (4.16.0)

humanize@4.10.0 で版を固定していたため、poetry update では上がりませんでした。@latest で書き換えると 4.16.0 になりました。

install と sync の違い

poetry install は足りないものを入れるだけで、lock に無いものは消しません。 poetry sync は、lock に無いパッケージを消して lock とぴったり同じにします。仮想環境に pip で humanize を直接入れた状態で比べました。

$ poetry run pip install -q humanize
$ poetry install
Installing dependencies from lock file

No dependencies to install or update
$ poetry sync
Installing dependencies from lock file

Package operations: 0 installs, 0 updates, 1 removal

  - Removing humanize (4.16.0)

本番用に開発用のパッケージを外すときも、install --without dev では何も消えず、sync --without dev で pytest など5つが消えました。

$ poetry install --without dev
Installing dependencies from lock file

No dependencies to install or update
$ poetry sync --without dev
  - Removing iniconfig (2.3.1)
  - Removing packaging (26.3)
  - Removing pluggy (1.7.0)
  - Removing pygments (2.21.0)
  - Removing pytest (9.1.1)

clone したプロジェクトを動かす

他の人のプロジェクトを clone したら、poetry install の1行で lock どおりの環境ができます。仮想環境を消してから入れ直すと、10個のパッケージが約1.4秒で入りました（2回目でキャッシュがある状態）。

$ poetry env remove --all
$ poetry install
Creating virtualenv hello-poetry-wfzNIG1A-py3.11 in /home/user/.cache/pypoetry/virtualenvs
Installing dependencies from lock file

Package operations: 10 installs, 0 updates, 0 removals
...
Installing the current project: hello-poetry (0.2.0)

requirements.txt に書き出す（poetry export）

Docker イメージや他のツールのために requirements.txt が要るときは poetry export を使います。2.x では本体に入っていないため、プラグインを足します。 pipx で入れた Poetry には pipx inject で足します。

$ poetry export -f requirements.txt
The requested command export does not exist.

Documentation: https://python-poetry.org/docs/cli/
$ pipx inject poetry poetry-plugin-export
  injected package poetry-plugin-export into venv poetry
$ poetry export -f requirements.txt --output requirements.txt --without-hashes
$ cat requirements.txt
certifi==2026.10.19 ; python_version >= "3.11"
charset-normalizer==3.5.2 ; python_version >= "3.11"
idna==3.20 ; python_version >= "3.11"
requests==2.34.2 ; python_version >= "3.11"
urllib3==2.8.0 ; python_version >= "3.11"

公式インストーラーで入れた場合は poetry self add poetry-plugin-export です。プロジェクトで必須にするなら、pyproject.toml の [tool.poetry.requires-plugins] に書く方法もあります。

Poetryでパッケージをビルド・公開する

poetry build で、PyPI に上げられる wheel（.whl）と sdist（.tar.gz）が dist/ にできます。 版は poetry version で上げます。

$ poetry version minor
Bumping version from 0.1.0 to 0.2.0
$ poetry build
Building hello-poetry (0.2.0)
Building sdist
  - Building sdist
  - Built hello_poetry-0.2.0.tar.gz
Building wheel
  - Building wheel
  - Built hello_poetry-0.2.0-py3-none-any.whl
$ python3 -m zipfile -l dist/hello_poetry-0.2.0-py3-none-any.whl
File Name                                             Modified             Size
hello_poetry/__init__.py                       2016-01-01 00:00:00          137
hello_poetry-0.2.0.dist-info/METADATA          2016-01-01 00:00:00          525
hello_poetry-0.2.0.dist-info/WHEEL             2016-01-01 00:00:00           88
hello_poetry-0.2.0.dist-info/entry_points.txt  2016-01-01 00:00:00           43
hello_poetry-0.2.0.dist-info/RECORD            2016-01-01 00:00:00          400

wheel は 1,470 バイト、sdist は 750 バイトでした。[project.scripts] の hello は entry_points.txt に入り、pip で入れた人も hello コマンドを使えます。poetry version には patch・minor・major のほか、prerelease などもあります。

公開は poetry publish です。公式ドキュメントでは、PyPI の API トークンを poetry config pypi-token.pypi <トークン> で設定してから実行します。--build を付けるとビルドもまとめて行い、--dry-run で上げずに確かめられます。

アプリだけ作るとき（package-mode = false）

Web アプリやスクリプト集のように、パッケージとして配布しないプロジェクトは「パッケージモード」を切ります。切らないまま、パッケージのフォルダが無い状態で poetry install すると、依存は入っても最後にエラーになります。

$ poetry install
Installing the current project: new-py (0.1.0)

Error: The current project could not be installed: No file/folder found for package new-py
If you do not want to install the current project use --no-root.
If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
If you did intend to install the current project, you may need to set `packages` in your pyproject.toml file.

[tool.poetry]
package-mode = false

足したあとは poetry install が通りました。このモードでは name・version を省略でき、ビルドはできなくなります（poetry build は Building a package is not possible in non-package mode. で止まりました）。

Poetryのコマンド一覧

Poetry 2.5.1 の poetry list に出るコマンドから、よく使うものをまとめます（export はプラグイン）。

コマンド	何をするか
poetry new <名前>	プロジェクトのフォルダを作る（--flat で src なし）
poetry init	今のフォルダに pyproject.toml を作る
poetry add <パッケージ>	依存を追加して入れる（--group dev・--dry-run）
poetry remove <パッケージ>	依存を外す
poetry install	lock どおりに入れる（--no-root・--without・--with・--only）
poetry sync	lock と同じにする（余分を消す）
poetry update [パッケージ]	範囲の中で最新にし、lock を書き直す
poetry lock	lock だけ作り直す（入れない）
poetry show	入っているパッケージ（--tree・--outdated・--latest・--why）
poetry run <コマンド>	仮想環境の中で実行する
poetry env info / list / use / remove	仮想環境の確認・切り替え・削除
poetry env activate	有効化のコマンドを表示する
poetry check	pyproject.toml と lock の整合を確かめる
poetry build / publish	配布物を作る／PyPI に上げる
poetry version [patch|minor|major]	版を表示する・上げる
poetry config	設定の確認・変更（--list・--local）
poetry source add	PyPI 以外のパッケージの置き場所を足す
poetry python install / list / remove	Python 本体の管理（実験的）
poetry self update / self add	Poetry 自身の更新・プラグインの追加
poetry cache clear / list	キャッシュの削除・一覧
poetry export	requirements.txt などに書き出す（プラグイン）

関連記事「pytest 使い方｜導入からfixture・mock・カバレッジまで実行結果つき」で扱っています。

asdfとは

asdf（アスディーエフ）は、Python・Node.js・Java・Go・Terraform などの版を、1つのコマンドで切り替えるツールです。 言語ごとに pyenv・nvm・rbenv を使い分ける代わりに、プラグインを足して同じ操作で管理します。

仕組み	説明
プラグイン	言語・ツールごとの「入れ方」を書いたもの。asdf plugin add python で足す
.tool-versions	フォルダごとに「どの版を使うか」を書くファイル。1行に「名前 版」
shims	python・node などと同じ名前の小さなスクリプト。PATH の先頭に置き、呼ばれると版を決めて本物を動かす
~/.asdf	入れた版（installs）・プラグイン（plugins）・shims を置く場所（ASDF_DATA_DIR で変更可）

公式ドキュメントは、asdf を「パッケージマネージャーではなく、ツールのバージョンマネージャー」と説明しています。OS の依存ライブラリまでは管理しません。

asdfのインストール（0.16以降）

0.16.0 以降の asdf は、1つの実行ファイルを PATH に置き、shims のフォルダを PATH の先頭に足すだけです。 以前の git clone して asdf.sh を読み込む方法とは手順が違います。2026年10月22日時点の最新は 0.20.2（2026年9月22日公開）です。

方法	コマンド
Mac（Homebrew）	brew install asdf
Linux（バイナリ）	GitHub のリリースから asdf-v0.20.2-linux-amd64.tar.gz を取り、展開した asdf を PATH の通ったフォルダに置く
Go で入れる	go install github.com/asdf-vm/asdf/cmd/asdf@v0.20.2
Arch Linux	AUR の asdf-vm
Windows	ネイティブは対象外。WSL2 の Linux で上と同じ手順

公式の FAQ によると、WSL2 では動く想定で、作業フォルダが Windows 側のドライブではなく Linux 側にあることが条件です。WSL1 は公式には対象外です。依存として git が要ります（Mac は brew install coreutils git bash）。

シェルの設定

shims のフォルダを PATH の先頭に足します。公式ドキュメントの1行です。

# bash は ~/.bash_profile、zsh は ~/.zshrc に足す
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

補完を使う場合は次のとおりです。

# bash（~/.bashrc）
. <(asdf completion bash)

# zsh
mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"
asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"
# ~/.zshrc に次の2行を足す
fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)
autoload -Uz compinit && compinit

fish では ~/.config/fish/config.fish に shims を PATH の先頭に足す処理を書き、補完は asdf completion fish > ~/.config/fish/completions/asdf.fish で入れます（公式ドキュメントのコードは fish_add_path を使わない形です）。

入れたあとの確認です。type -a asdf の1行目に、置いたフォルダが出れば準備完了です。

$ type -a asdf
asdf is /home/user/bin/asdf
$ asdf --version
asdf version v0.20.2 (revision cb72590)

asdfの使い方：Pythonを入れて切り替える

asdf の基本は「plugin add → install → set」の3つです。 Python を例に、2つの版を入れて切り替えました。

flowchart TD
    A[asdf plugin add python] --> B[asdf install python 3.13.7]
    B --> C[asdf set -u python 3.13.7<br>いつも使う版]
    B --> D[asdf set python 3.12.3<br>このフォルダの版]
    C --> E[python で版が切り替わる]
    D --> E

プラグインを足して版を調べる

$ asdf plugin add python
$ asdf plugin list --urls
python      https://github.com/danhper/asdf-python.git
$ asdf list all python | wc -l
1140
$ asdf list all python 3.13 | tail -3
3.13.16t
3.13.17
3.13.17t
$ asdf latest python 3.12
3.12.15
$ asdf latest python
3.15.1t

asdf plugin add に名前だけ渡すと、公式のプラグイン一覧（asdf-plugins）から URL が決まります。一覧には 845 件ありました。主なものは次のとおりです。

$ asdf plugin list all | grep -E '^(python|nodejs|java|terraform|poetry|golang|ruby) '
golang                                      https://github.com/asdf-community/asdf-golang.git
java                                        https://github.com/halcyon/asdf-java.git
nodejs                                      https://github.com/asdf-vm/asdf-nodejs.git
poetry                                      https://github.com/asdf-community/asdf-poetry.git
python                                      https://github.com/danhper/asdf-python.git
ruby                                        https://github.com/asdf-vm/asdf-ruby.git
terraform                                   https://github.com/asdf-community/asdf-hashicorp.git

asdf latest python は、末尾に t が付いたフリースレッド版（3.15.1t）を返しました。 版の数字だけを見て latest を使うと、意図しない版が入ることがあります。asdf latest python 3.12 のように系列を付けるか、版を明示します。

asdf install で入れる

asdf-python は、内部で pyenv の python-build を使って Python をソースからビルドします。ビルドに要るパッケージ（Ubuntu なら build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libffi-dev liblzma-dev tk-dev など）を先に入れておきます。

$ time asdf install python 3.13.7
python-build 3.13.7 /home/user/.asdf/installs/python/3.13.7
Installing Python-3.13.7...
Installed Python-3.13.7 to /home/user/.asdf/installs/python/3.13.7

real    5m33.725s
$ time asdf install python 3.12.3
python-build 3.12.3 /home/user/.asdf/installs/python/3.12.3
Installing Python-3.12.3...
Installed Python-3.12.3 to /home/user/.asdf/installs/python/3.12.3

real    3m22.628s
$ asdf list python
  3.12.3
 *3.13.7

入れただけでは、まだ使えません。版を決めていない状態で python を打つと、asdf はエラーにします（pyenv のように OS の Python へは進みません）。

$ type -a python
python is /home/user/.asdf/shims/python
python is /usr/bin/python
$ python --version
No version is set for command python
Consider adding one of the following versions in your config file at /home/user/.tool-versions
python 3.13.7
$ asdf current
Name            Version         Source          Installed
python          ______          ______          

asdf set -u：いつも使う版を決める

-u（--home）を付けると、ホームの ~/.tool-versions に書かれます。0.15 までの asdf global に当たります。

$ asdf set -u python 3.13.7
$ cat ~/.tool-versions
python 3.13.7
$ python --version
Python 3.13.7
$ asdf current
Name            Version         Source                       Installed
python          3.13.7          /home/user/.tool-versions    true
$ asdf which python
/home/user/.asdf/installs/python/3.13.7/bin/python
$ asdf where python
/home/user/.asdf/installs/python/3.13.7

asdf set：このフォルダの版を決める

フラグなしの asdf set は、今のフォルダの .tool-versions に書きます。0.15 までの asdf local に当たります。

$ mkdir -p ~/work/legacy-app/src && cd ~/work/legacy-app
$ asdf set python 3.12.3
$ cat .tool-versions
python 3.12.3
$ python --version
Python 3.12.3
$ cd src && python --version
Python 3.12.3
$ cd ~ && python --version
Python 3.13.7

下のフォルダ（src）でも、親をさかのぼって見つけた .tool-versions が使われます。 ホームに戻ると -u で決めた 3.13.7 に戻りました。

環境変数で今だけ版を変える

ASDF_<ツール名>_VERSION の環境変数は、.tool-versions より優先されます。0.15 までの asdf shell の代わりです。

$ cd ~/work/legacy-app
$ ASDF_PYTHON_VERSION=3.13.7 python --version
Python 3.13.7
$ export ASDF_PYTHON_VERSION=3.13.7
$ asdf current python
Name            Version         Source              Installed
python          3.13.7          ASDF_PYTHON_VERSION true
$ unset ASDF_PYTHON_VERSION

複数の版を並べる・system を使う

1行に版を並べると、最初の版が python になり、2番目以降は python3.13 のような版付きの名前で呼べます。system は asdf 以外で入っている Python（ここでは OS の 3.11.15）を指します。

$ asdf set python 3.12.3 3.13.7
$ cat .tool-versions
python 3.12.3 3.13.7
$ python --version; python3.13 --version
Python 3.12.3
Python 3.13.7
$ asdf set python system
$ python --version
Python 3.11.15

pip で入れたコマンドと reshim

asdf の Python に pip でコマンド付きのパッケージを入れると、asdf-python が自動で shims を作り直します（Reshimming asdf python...）。作られないときは asdf reshim python を実行します。

$ pip install -q cowsay
Reshimming asdf python...
$ ls ~/.asdf/shims | grep cow
cowsay
$ cowsay -t hi | head -3
  __
| hi |
  ==
$ cd ~ && cowsay -t hi
No version is set for command cowsay
Consider adding one of the following versions in your config file at /home/user/.tool-versions
python 3.12.3
$ asdf shimversions cowsay
python 3.12.3

パッケージは版ごとに別々です。 3.13.7 を使うホームでは、3.12.3 にだけ入れた cowsay は「No version is set」になりました。どの版に入っているかは asdf shimversions で分かります。

.tool-versionsとバージョンが決まる順番

.tool-versions は「ツール名 版」を1行ずつ書いたテキストファイルです。 Python と Node.js など、複数のツールを1つのファイルに書けます。

# このプロジェクトの版
python 3.12.3
nodejs 24.0.0
terraform 1.9.8

書ける値	意味
3.12.3	正確な版（latest や 3.12 のような範囲は書けない）
3.12.3 3.13.7	複数の版。前にあるものが優先
system	asdf 以外で入っている版
ref:v3.12.3	Git のタグ・ブランチ・コミットからビルド（対応するプラグインのみ）
path:/opt/python	自分でビルドした版のフォルダ

公式の FAQ によると、.tool-versions に latest や版の範囲を書けないのは、同じファイルから毎回同じ版を入れられるようにするためです。

asdf が版を探す順番は次のとおりです。

flowchart TD
    A[1 環境変数<br>ASDF_PYTHON_VERSION] -->|無ければ| B[2 今のフォルダの<br>.tool-versions]
    B -->|無ければ| C[3 親フォルダを<br>さかのぼる]
    C -->|無ければ| D[4 ホームの<br>.tool-versions]
    D -->|無ければ| E[エラー<br>No version is set]

決まった理由は asdf current の Source 列に出ます。版を間違えたと思ったら、まずここを見ます。

.python-version や .nvmrc も読ませる

~/.asdfrc に legacy_version_file = yes を書くと、プラグインが対応していれば .python-version（pyenv）や .nvmrc（nvm）も読みます。pyenv や nvm から移るときに、既存のファイルをそのまま使えます。

~/.asdfrc の項目	既定	意味
legacy_version_file	no	yes で .python-version・.nvmrc なども読む
always_keep_download	no	yes でダウンロードしたソースを残す
concurrency	auto	ビルドに使うコア数
plugin_repository_last_check_duration	60	プラグイン一覧を更新する間隔（分）

asdf 0.16以降で変わったこと（global・localが使えない）

asdf 0.16.0（2025年1月）で Go に書き直され、asdf global・asdf local・asdf shell が無くなりました。 0.15 までの手順をそのまま打つと、次のように止まります（後ろにヘルプの全文が続きます）。

$ asdf global python 3.13.7
invalid command provided: global

version: v0.20.2 (revision cb72590)
...
$ asdf local python 3.13.7
invalid command provided: local
$ asdf shell python 3.13.7
invalid command provided: shell
$ asdf plugin-add nodejs
invalid command provided: plugin-add

ほかに、ハイフン付きのコマンド（plugin-add・list-all・shim-versions など）は空白区切り（plugin add・list all・shimversions）だけになり、asdf current の表示は「Source」と「Installed」の2列に分かれました。

公式の移行ガイドの手順は次のとおりです。

1. 新しい asdf のバイナリを PATH に置く。
2. asdf info で ASDF_DATA_DIR を確かめ、独自の場所ならシェルの設定で export する。
3. $ASDF_DATA_DIR/shims を PATH の先頭に足す。
4. asdf.sh などを読み込む以前の行を消す。
5. asdf --help で 0.16.0 以上と確かめ、asdf reshim を実行する。

入れた版（installs）とプラグイン（plugins）はそのまま使えます。

asdfのコマンド一覧

asdf 0.20.2 の asdf --help に出るコマンドです。

コマンド	何をするか
asdf plugin add <名前> [Git の URL]	プラグインを足す
asdf plugin list [--urls]	入っているプラグイン
asdf plugin list all	公式一覧にあるプラグイン
asdf plugin update --all	プラグインを更新する
asdf plugin remove <名前>	プラグインと、その版をすべて消す
asdf install	.tool-versions に書かれた版をすべて入れる
asdf install <名前> <版>	版を指定して入れる（latest:3.13 も可）
asdf uninstall <名前> <版>	版を消す
asdf set [-u] [-p] <名前> <版>	.tool-versions に書く
asdf current [名前]	今の版と、決まった理由
asdf list <名前>	入っている版（* が今の版）
asdf list all <名前> [前方一致]	入れられる版
asdf latest <名前> [前方一致]	最新の安定版
asdf which <コマンド>	実際に動く本物のパス
asdf where <名前>	版のフォルダ（JAVA_HOME の設定などに使う）
asdf exec <コマンド>	今の版で実行する
asdf reshim <名前> <版>	shims を作り直す
asdf shimversions <コマンド>	そのコマンドを持つ版
asdf info	OS・シェル・asdf の設定の表示（不具合の報告用）

asdf where は、たとえば Java のプラグインで export JAVA_HOME=$(asdf where java) のように、ツールの場所を他の設定に渡すときに使えます。

Poetryとasdfを組み合わせる

asdf の .tool-versions で Python の版を決めたフォルダで Poetry を使うと、その Python で仮想環境が作られます。 Poetry 2.x は「今 python で動く Python」で仮想環境を作るためです。

$ cd ~/work/legacy-app
$ cat .tool-versions
python 3.12.3
$ poetry init -n --name legacy-app --python '>=3.12,<3.13'
$ poetry add humanize
Creating virtualenv legacy-app-n_e2E8Qq-py3.12 in /home/user/.cache/pypoetry/virtualenvs
Using version ^4.16.0 for humanize
...
$ poetry env info

Virtualenv
Python:         3.12.3
Implementation: CPython
Path:           /home/user/.cache/pypoetry/virtualenvs/legacy-app-n_e2E8Qq-py3.12
Executable:     /home/user/.cache/pypoetry/virtualenvs/legacy-app-n_e2E8Qq-py3.12/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.12.3
Path:       /home/user/.asdf/installs/python/3.12.3
Executable: /home/user/.asdf/installs/python/3.12.3/bin/python3.12
$ poetry run python -c 'import humanize; print(humanize.naturalsize(10**6))'
1.0 MB

Base の Path が asdf の 3.12.3 を指しています。Poetry 自体は pipx の Python 3.11 で動いていますが、仮想環境は asdf の 3.12.3 で作られました。

.tool-versions を requires-python の範囲の外（3.13.7）に変えると、Poetry は警告を出して PATH から合う版を探しました。

$ asdf set python 3.13.7
$ poetry run python --version
The currently activated Python version 3.13.7 is not supported by the project (>=3.12,<3.13).
Trying to find and use a compatible version. 
Using python3.12 (3.12.3)
Python 3.12.3

.tool-versions と requires-python をそろえておくと、この警告が出ず、誰の PC でも同じ版の仮想環境になります。

• 1.tool-versions の Python の版が、requires-python の範囲に入っている外れていると Poetry が別の Python を探しにいく
• 2.tool-versions・pyproject.toml・poetry.lock の3つをコミットしているclone した人は asdf install と poetry install の2行で同じ環境になる
• 3Poetry 本体は pipx など、プロジェクトとは別の場所に入れている公式ドキュメントは、プロジェクトの仮想環境に Poetry を入れないよう注意している
• 4Python の版を変えたら、前の版の仮想環境を消しているpoetry env list で版ごとの環境が残っていないか見る
• 5CI では Poetry の版を固定しているpipx install poetry==2.5.1 のように書く

clone した人が環境を作る手順は次の2行です。

asdf install       # .tool-versions の版をすべて入れる
poetry install     # poetry.lock どおりに依存を入れる

Poetry も asdf で管理する

asdf には Poetry 自体のプラグイン（asdf-poetry）もあり、.tool-versions に poetry 2.5.1 と書いて Poetry の版もそろえられます。公式ドキュメントが推奨する入れ方は pipx と公式インストーラーなので、どちらで入れるかはチームで決めます。

shims を通すと起動が少し遅くなる

asdf の shim は asdf exec を呼ぶ小さな bash スクリプトです。

#!/usr/bin/env bash
# asdf-plugin: python 3.13.7
exec asdf exec "python" "$@"

python -c pass を50回ずつ実行し、1回あたりの時間を3回測りました。

呼び方	1回あたり（3回の測定）
shim 経由（python）	16.0・15.5・16.6 ミリ秒
本物を直接（~/.asdf/installs/python/3.12.3/bin/python）	11.3・11.5・11.5 ミリ秒

差は1回あたり約5ミリ秒です。poetry run や仮想環境の中では、仮想環境の python が直接呼ばれるため、この差はかかりません。

pyenv・uv・pip+venv・miseとの違い

Python の版を切り替えるのが pyenv・asdf・mise、依存を管理するのが Poetry・pip+venv、両方を1つで行うのが uv です。 公式ドキュメントで確かめた事実を並べます。

ツール	管理するもの	版・依存を書くファイル	Python 本体	動く OS
Poetry	依存・仮想環境・ビルド・公開	pyproject.toml・poetry.lock	原則入れない（実験的な poetry python）	Linux・Mac・Windows
asdf	多言語の版（プラグイン）	.tool-versions	入れる（Python はソースからビルド）	Linux・Mac・WSL2
pyenv	Python の版	.python-version	入れる（ソースからビルド）	Linux・Mac（Windows は pyenv-win）
uv	版・仮想環境・依存・CLI ツール	pyproject.toml・uv.lock	入れる（ビルド済み）	Linux・Mac・Windows
pip + venv	依存（venv で分ける）	requirements.txt	入れない	Linux・Mac・Windows
mise	多言語の版・環境変数	mise.toml（.tool-versions も読む）	入れる	Linux・Mac・Windows

状況	選ぶもの	理由
Python も Node.js も Terraform も版をそろえたい	asdf または mise	1つのファイルで複数の言語を管理できる
Python の版だけを切り替えたい	pyenv	Python 専用で情報が多い
依存の解決・lock・パッケージの公開まで行いたい	Poetry	依存とビルドを1つのツールで扱える
版も依存も1つのツールにまとめたい	uv	Python の取得から lock まで行う
標準ライブラリだけで済ませたい	pip + venv	追加のツールが要らない
Windows でもネイティブに版をそろえたい	mise または uv	asdf のプラグインは Unix のシェルスクリプト

mise の公式ドキュメントは、mise が .tool-versions を読み、asdf のプラグインも使えるため、プロジェクトごとに移行できると説明しています。主なコマンドの対応は次のとおりです。

操作	asdf	mise
版を入れる	asdf install nodejs 24.0.0	mise install node@24.0.0
プロジェクトの版を決める	asdf set nodejs 24.0.0	mise use node@24.0.0
いつもの版を決める	asdf set -u nodejs 24.0.0	mise use -g node@24.0.0
今の版	asdf current	mise ls --current

関連記事「pyenvとは｜インストール・使い方・仕組みとエラーの直し方」で扱っています。

関連記事「uvの使い方｜pip・venvからの移行とチーム開発での使い方」で扱っています。

関連記事「Python venvの使い方｜仮想環境の作成・有効化・削除をOS別にコピペ」で扱っています。

関連記事「Node.js バージョン管理｜nvm・fnm・mise・Volta比較と実測」で扱っています。

Poetry・asdfでよくあるエラーと直し方

実際に出したエラーの原文と、原因・直し方です。上が Poetry、下が asdf です。

エラー・症状（原文）	原因	直し方
poetry: command not found	~/.local/bin が PATH に無い	pipx ensurepath のあと端末を開き直す
Looks like you're trying to use a Poetry command that is not available.（shell）	2.0 で shell が本体から外れた	eval "$(poetry env activate)"
The requested command export does not exist.	export はプラグインになった	pipx inject poetry poetry-plugin-export
pyproject.toml changed significantly since poetry.lock was last generated.	手で直して lock を作り直していない	poetry lock のあと poetry install
The current project's supported Python range (>=3.8) is not compatible with ...	requires-python が依存より広い	requires-python を >=3.10 などに狭める
No file/folder found for package new-py	パッケージのフォルダが無い	package-mode = false か --no-root
Could not find a matching version of package ...	名前の誤り・PyPI に無い	PyPI で正しい名前を確かめる
Could not find the python executable python3.9	その版の Python が無い	asdf などで入れてから poetry env use
Poetry could not find a pyproject.toml file in ... or its parents	プロジェクトの外で実行した	cd するか -C <フォルダ> を付ける
Cannot add dependency on humanize to project with the same name.	プロジェクト名と依存の名前が同じ	pyproject.toml の name を変える
Command not found: hello	scripts を足した後に入れ直していない	poetry install
Building a package is not possible in non-package mode.	package-mode = false で build した	配布するならパッケージモードに戻す
The currently activated Python version 3.11.15 is not supported by the project	PATH の Python が範囲外	asdf で範囲内の版にする・poetry env use
invalid command provided: global（local・shell・plugin-add）	0.16 で無くなったコマンド	asdf set -u・asdf set・asdf plugin add
No version is set for command python	どの .tool-versions にも版が無い	asdf set か asdf set -u で決める
false - Run `asdf install python 3.11.9`（current の表示）	書いた版が入っていない	asdf install
python-build: definition not found: 3.99.0	その版が無い・プラグインの定義が少ない	asdf list all python で確かめる・asdf plugin update python
error installing version: Plugin named nodejs not installed	プラグインを足していない	asdf plugin add nodejs
error: failed to download Python-3.11.9.tar.xz	python.org に届かない（プロキシ等）	https_proxy を設定する

The current project's supported Python range is not compatible

poetry init の requires-python が >=3.8 のプロジェクトに、Python 3.10 以上が要る pytest 9 を足したときの出力です。

$ poetry add pytest
Using version ^9.1.1 for pytest

Updating dependencies
Resolving dependencies...

The current project's supported Python range (>=3.8) is not compatible with some of the required packages Python requirement:
  - pytest requires Python >=3.10, so it will not be installable for Python >=3.8,<3.10

Because no versions of pytest match >9.1.1,<10.0.0
 and pytest (9.1.1) requires Python >=3.10, pytest is forbidden.
So, because old-py depends on pytest (^9.1.1), version solving failed.

  * Check your dependencies Python requirement: The Python requirement can be specified via the `python` or `markers` properties

    For pytest, a possible solution would be to set the `python` property to ">=3.10"

Poetry は、requires-python の範囲のすべての版で依存が入れられるかを確かめます。3.8・3.9 では pytest 9 が入らないため、解決に失敗します。requires-python = ">=3.10" に狭めると通ります。

No version is set for command python

asdf で版を決めていない、または .tool-versions に書いた版が入っていないときに出ます。入っていない 3.11.9 を書いたときは、次のように入っている版の候補が表示され、asdf current では Installed が false になりました。

$ asdf set python 3.11.9
$ python --version
No version is set for command python
Consider adding one of the following versions in your config file at /home/user/work/legacy-app/.tool-versions
python 3.13.7
python 3.12.3
$ asdf current python
Name            Version         Source                                    Installed
python          3.11.9          /home/user/work/legacy-app/.tool-versions false - Run `asdf install python 3.11.9`

asdf install を打つと .tool-versions の版が入ります。pyenv は入っていない版でも OS の Python へ黙って進みますが、asdf はエラーで止まります。 どちらの動きかを知っておくと、原因を早く見つけられます。

asdf install でダウンロードに失敗する

python.org からソースを取れないときの出力です。プロキシに断られ、HTTP 403 が返っています。

$ asdf install
python-build 3.11.9 /home/user/.asdf/installs/python/3.11.9
Downloading Python-3.11.9.tar.xz...
-> https://www.python.org/ftp/python/3.11.9/Python-3.11.9.tar.xz
error: failed to download Python-3.11.9.tar.xz

BUILD FAILED (Ubuntu 24.04 using python-build 2.8.11-1-g7d65a468)

Last 10 log lines:
curl: (22) The requested URL returned error: 403
failed to run install callback: exit status 1

python-build は http_proxy・https_proxy の環境変数を使います。また、PYTHON_BUILD_CACHE_PATH で指定したフォルダに同じ名前のソース（例：Python-3.12.3.tar.xz）を置くと、ダウンロードせずにそれを使います。この記事の 3.12.3 と 3.13.7 は、この方法で置いたソースからビルドしました（定義ファイルの SHA-256 と照合されます）。ビルドの途中で止まる場合の原因と直し方は、pyenv と同じです。

Plugin named nodejs not installed

.tool-versions に nodejs 24.0.0 を書いても、nodejs のプラグインが無いと asdf current に表示されず、node は OS の Node.js のまま動きました。

$ cat .tool-versions
python 3.12.3
nodejs 24.0.0
$ node --version
v22.22.2
$ asdf current
Name            Version         Source                                    Installed
python          3.12.3          /home/user/work/legacy-app/.tool-versions true
$ asdf install nodejs 24.0.0
error installing version: Plugin named nodejs not installed

asdf plugin add nodejs でプラグインを足してから asdf install を実行します。

Poetry・asdfのアップデートとアンインストール

やりたいこと	コマンド
Poetry を更新（pipx）	pipx upgrade poetry
Poetry を更新（公式インストーラー）	poetry self update
Poetry を消す（pipx）	pipx uninstall poetry
Poetry を消す（公式インストーラー）	curl -sSL https://install.python-poetry.org | python3 - --uninstall
asdf を更新	brew upgrade asdf、またはバイナリを入れ替える
asdf のプラグインを更新	asdf plugin update --all
asdf の版を消す	asdf uninstall python 3.12.3
asdf のプラグインと版をまとめて消す	asdf plugin remove python

$ asdf uninstall python 3.12.3
$ asdf list python
 *3.13.7
$ asdf plugin remove python
$ asdf current
No plugins installed
$ pipx uninstall poetry
uninstalled poetry! ✨ 🌟 ✨
$ du -sh ~/.cache/pypoetry
48M /home/user/.cache/pypoetry

pipx uninstall poetry では、プロジェクトの仮想環境とキャッシュは残ります（ここでは 48MB）。不要なら ~/.cache/pypoetry を消します。asdf を完全に消すときは、シェルの設定から shims の行を消し、~/.asdf と asdf の実行ファイルを消します。入れた版もすべて消えます。

よくある質問

Q. Poetry とは何ですか？ A. Python のプロジェクトの依存関係・仮想環境・パッケージのビルドと公開をまとめて行うツールです。pyproject.toml に依存を書き、poetry.lock で正確な版を固定します。

Q. asdf とは何ですか？ A. Python・Node.js・Java など、複数の言語やツールの版をプラグインで切り替えるバージョン管理ツールです。フォルダごとの版を .tool-versions に書きます。

Q. Poetry と asdf の違いは？ A. Poetry はプロジェクトの依存パッケージを、asdf は言語そのものの版を管理します。asdf で Python の版を決め、Poetry で依存を管理する組み合わせで使えます。「Poetryとasdfを組み合わせる」で実例を載せています。

Q. Poetry の使い方の基本は？ A. poetry new（または poetry init）でプロジェクトを作り、poetry add で依存を足し、poetry run で実行します。clone したプロジェクトは poetry install で同じ環境になります。

Q. asdf の使い方の基本は？ A. asdf plugin add python でプラグインを足し、asdf install python 3.13.7 で入れ、asdf set python 3.13.7（フォルダ）か asdf set -u python 3.13.7（ホーム）で版を決めます。

Q. asdf global が使えません。 A. asdf 0.16.0 で asdf global・asdf local は無くなりました。asdf global は asdf set -u、asdf local は asdf set に置き換えます。

Q. poetry shell が使えません。 A. Poetry 2.0 から本体に含まれなくなりました。eval "$(poetry env activate)" で有効にするか、poetry-plugin-shell を入れます。

Q. Poetry で requirements.txt を出力するには？ A. poetry-plugin-export を入れて poetry export -f requirements.txt --output requirements.txt を実行します。2.x では本体に入っていません。

Q. Poetry の仮想環境はどこにありますか？ A. poetry env info --path で分かります。Linux の既定は ~/.cache/pypoetry/virtualenvs です。poetry config virtualenvs.in-project true でプロジェクト直下の .venv に作れます。

Q. Poetry と uv の違いは？ A. Poetry は依存・仮想環境・ビルドを管理し、Python 本体は原則入れません。uv は Python の取得・仮想環境・依存・CLI ツールまでを1つで行います。lock ファイルは Poetry が poetry.lock、uv が uv.lock です。

Q. asdf と mise の違いは？ A. どちらも複数の言語の版を管理します。mise は .tool-versions を読み、asdf のプラグインも使えて、Windows でもネイティブに動きます。asdf の版の切り替えは shims で行われます。

Q. asdf は Windows で使えますか？ A. ネイティブの Windows は対象外です。公式の FAQ では、WSL2 で動く想定（作業フォルダは Linux 側）とされています。

まとめ

• Poetry はプロジェクトの依存・仮想環境・ビルドを、asdf は言語の版を管理する。組み合わせて使える。
• Poetry 2.x では依存は [project]、開発用は [dependency-groups] に書かれる。shell・export は本体から外れた。
• poetry install は足りないものを入れるだけ。lock とぴったり同じにするのは poetry sync。
• asdf 0.16 以降は asdf global・local が無く、asdf set -u・asdf set を使う。
• asdf は版が決まっていないと No version is set で止まる。理由は asdf current の Source 列で分かる。
• .tool-versions の Python の版を requires-python の範囲に入れておくと、Poetry がその版で仮想環境を作る。

参考・出典

確認日はいずれも 2026年10月22日です。

• Poetry「Introduction（インストール）」：https://python-poetry.org/docs/
• Poetry「Basic usage」：https://python-poetry.org/docs/basic-usage/
• Poetry「Commands」：https://python-poetry.org/docs/cli/
• Poetry「The pyproject.toml file」：https://python-poetry.org/docs/pyproject/
• Poetry「Managing dependencies」：https://python-poetry.org/docs/managing-dependencies/
• Poetry「Managing environments」：https://python-poetry.org/docs/managing-environments/
• Poetry「Configuration」：https://python-poetry.org/docs/configuration/
• PyPI「poetry」：https://pypi.org/project/poetry/
• PyPI「poetry-plugin-export」：https://pypi.org/project/poetry-plugin-export/
• PyPI「poetry-plugin-shell」：https://pypi.org/project/poetry-plugin-shell/
• asdf「Introduction」：https://asdf-vm.com/guide/introduction.html
• asdf「Getting Started」：https://asdf-vm.com/guide/getting-started.html
• asdf「Upgrading to 0.16.0」：https://asdf-vm.com/guide/upgrading-to-v0-16.html
• asdf「Versions」：https://asdf-vm.com/manage/versions.html
• asdf「Configuration」：https://asdf-vm.com/manage/configuration.html
• asdf「FAQ」：https://asdf-vm.com/more/faq.html
• asdf CHANGELOG：https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md
• asdf-python：https://github.com/asdf-community/asdf-python
• mise「Comparison to asdf」：https://mise.jdx.dev/dev-tools/comparison-to-asdf.html
• uv：https://docs.astral.sh/uv/
• uv「Project structure and files」：https://docs.astral.sh/uv/concepts/projects/layout/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。