Poetry on Ubuntu 応用 — 仮想環境・依存関係管理のベストプラクティス

開発環境

この記事のポイント

  • Ubuntu 24.04 LTS では pip install poetry が PEP 668 エラーになる → pipx 経由が公式推奨（実測確認）
  • Poetry 2.4.1 の pyproject.toml は PEP 621 形式（[project] セクション）に変わった
  • 依存グループは poetry add --group dev pytest で追加、[dependency-groups] に書かれる
  • poetry export コマンドは Poetry 2.x 以降は標準外 → poetry-plugin-export が必要
  • poetry lock --check は廃止 → 代わりに poetry check を使う
  • 本番環境に dev ツールを混ぜない: poetry install --without dev

Poetryを使い始めて「poetry add は何となく動く」という段階に来たら、次は依存グループの使い方・仮想環境の制御・lock ファイルの扱いを押さえておきたいところです。

この記事では、Ubuntu 24.04.4 LTS で Poetry 2.4.1 を実際に動かした結果をもとに、仮想環境管理・依存グループ・poetry export などの応用操作を手順付きで解説します。Poetry は 2.x で書き方がかなり変わっているので、古い記事の情報で詰まっている方にも参考になるはずです。

検証環境

本記事のコマンドはすべて docker run --rm ubuntu:24.04（Ubuntu 24.04.4 LTS / Python 3.12.3）で実行しています。Poetry のバージョンは 2.4.1（2026-06-22 時点の最新）です。Ubuntu 22.04 との動作差は バージョン比較 を参照してください。

目次

  1. Poetry のインストール（Ubuntu 24.04 の注意点）
  2. プロジェクト作成と pyproject.toml の新形式
  3. 依存グループで dev・test・docs を分ける
  4. 仮想環境の制御（env info / run / config）
  5. requirements.txt への書き出し（プラグイン必須）
  6. lock ファイルの管理
  7. 本番 vs 開発の使い分けパターン
  8. Ubuntu 22.04 vs 24.04 比較
  9. よくあるエラーと解決策
  10. まとめ

Poetry のインストール（Ubuntu 24.04 の注意点）

Ubuntu 24.04 LTS では、pip install poetry を直接実行するとエラーになります。




ubuntu@linuxlab: ~
$ pip3 install poetry
error: externally-managed-environment
note: If you believe this is a mistake, please contact your Python
installation or OS distribution provider. You can override this,
at the risk of breaking your Python installation or OS, by passing
–break-system-packages.

これは PEP 668 という仕様で、Ubuntu 24.04 以降はシステムの Python 環境を pip で壊さないように保護されています。推奨は pipx 経由のインストールです。

手順1：pipx で Poetry をインストールする




ubuntu@linuxlab: ~
$ sudo apt-get update && sudo apt-get install -y pipx
Setting up pipx (1.4.3-1) …
$ pipx install poetry
installed package poetry 2.4.1, installed using Python 3.12.3
These apps are now globally available
– poetry
$ pipx ensurepath
/root/.local/bin has been added to PATH
$ poetry –version
Poetry (version 2.4.1)
Poetry 2.4.1 インストール実測ログ（Ubuntu 24.04.4 LTS）
Poetry 2.4.1 インストール実測ログ（Ubuntu 24.04.4 LTS）

インストール後に pipx ensurepath を忘れずに実行してください。これをやらないと新しいターミナルセッションで poetry コマンドが見つからないことがあります。実際に私も最初はまって、シェルを開き直したら動いた、という経験があります。

バージョンによる違い

Ubuntu 22.04 では pip install poetry は警告なしで実行できますが、Ubuntu 24.04 LTS 以降は pipx 経由が必須です。新規環境は迷わず pipx を使いましょう。

プロジェクト作成と pyproject.toml の新形式

手順2：poetry new でプロジェクトを作る




ubuntu@linuxlab: ~
$ poetry new sample-app
Created package sample_app in sample-app
$ cd sample-app
$ ls
README.md pyproject.toml src/ tests/

poetry new は src レイアウトでプロジェクトを作ります。既存ディレクトリで始める場合は poetry init を使います。

Poetry 2.x の pyproject.toml — PEP 621 形式に変わった

Poetry 2.4.1 で生成される pyproject.toml は、旧バージョンと書き方が変わっています。




ubuntu@linuxlab: ~/sample-app
$ cat pyproject.toml
[project]
name = “sample-app”
version = “0.1.0”
description = “”
authors = [
{name = “Your Name”, email = “you@example.com”}
]
requires-python = “>=3.12”
dependencies = []

[tool.poetry]
packages = [{include = “sample_app”, from = “src”}]

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

旧バージョン（1.x）では [tool.poetry] セクションがメインでしたが、Poetry 2.x からは PEP 621 に準拠した [project] セクションが主体になりました。古い記事のコピーをそのまま使うとフォーマットが合わないので注意が必要です。

依存グループで dev・test・docs を分ける

Poetry の強みの一つが依存グループです。「本番の依存」と「開発ツール」を明確に分けて管理できます。

手順3：グループ別に依存関係を追加する




ubuntu@linuxlab: ~/sample-app
$ poetry add requests
– Installing certifi (2026.6.17)
– Installing charset-normalizer (3.4.7)
– Installing idna (3.18)
– Installing urllib3 (2.7.0)
– Installing requests (2.34.2)
Writing lock file
$ poetry add –group dev pytest black flake8
– Installing black (26.5.1)
– Installing pytest (9.1.1)
– Installing flake8 (7.3.0)
Writing lock file
$ poetry add –group test pytest-cov
– Installing pytest-cov (7.1.0)
$ poetry add –group docs mkdocs
– Installing mkdocs (1.6.1)

実行後の pyproject.toml を確認すると、[dependency-groups] セクションが自動で追加されています。




ubuntu@linuxlab: ~/sample-app
$ cat pyproject.toml
…(project セクション省略)…
[dependency-groups]
dev = [
“pytest (>=9.1.1,<10.0.0)”,
“black (>=26.5.1,<27.0.0)”,
“flake8 (>=7.3.0,<8.0.0)”
]
test = [
“pytest-cov (>=7.1.0,<8.0.0)”
]
docs = [
“mkdocs (>=1.6.1,<2.0.0)”
]
依存グループ定義と poetry show 実測結果
依存グループ定義と poetry show 実測結果

依存グループのポイント

  • 旧形式: [tool.poetry.group.dev.dependencies]
  • 新形式（Poetry 2.x）: [dependency-groups] セクション内の dev = [...]
  • どちらも poetry add --group dev <pkg> コマンドで操作できる
  • poetry show --only main で本番依存のみ一覧確認できる
pyproject.toml の新形式（実測）
pyproject.toml の新形式（実測）

poetry show で依存関係を確認する




ubuntu@linuxlab: ~/sample-app
$ poetry show –only main
certifi 2026.6.17 Python package for providing Mozilla’s CA Bundle.
charset-normalizer 3.4.7 The Real First Universal Charset Detector.
idna 3.18 Internationalized Domain Names in Applications.
requests 2.34.2 Python HTTP for Humans.
urllib3 2.7.0 HTTP library with thread-safe connection pooling.
$ poetry show
（全グループのパッケージが34件表示される）

仮想環境の制御（env info / run / config）

仮想環境の場所を確認する

Poetry はデフォルトで仮想環境を ~/.cache/pypoetry/virtualenvs/ に作ります。プロジェクト直下に置きたい場合は設定を変えます。




ubuntu@linuxlab: ~/sample-app
$ poetry env info
Virtualenv
Python: 3.12.3
Implementation: CPython
Path: /root/.cache/pypoetry/virtualenvs/sample-app-MdG-jWMr-py3.12
Executable: /root/.cache/pypoetry/virtualenvs/sample-app-MdG-jWMr-py3.12/bin/python
Valid: True

Base
Platform: linux
OS: posix
Python: 3.12.3
Path: /usr

プロジェクト直下の .venv/ に作る設定

VS Code や他のエディタとの連携を考えると、プロジェクト直下に .venv/ があった方が楽です。




ubuntu@linuxlab: ~/sample-app
$ poetry config virtualenvs.in-project true
$ poetry install
Installing dependencies from lock file
Installing the current project: sample-app (0.1.0)
$ ls
.venv/ README.md poetry.lock pyproject.toml src/ tests/
$ poetry env info
Path: /root/sample-app/.venv
Valid: True

設定の適用範囲

  • poetry config virtualenvs.in-project true はグローバル設定（全プロジェクトに適用）
  • プロジェクト単位にしたい場合: poetry config virtualenvs.in-project true --local
  • --local をつけると poetry.toml に書き込まれる

poetry run でコマンドを実行する

仮想環境を activate せずに、poetry run 経由でスクリプトやコマンドを実行できます。CI/CD での使用に向いています。




ubuntu@linuxlab: ~/sample-app
$ poetry run python –version
Python 3.12.3
$ poetry run python -c “import requests; print(requests.__version__)”
2.34.2
$ poetry run pytest tests/
========================= test session starts ==========================
platform linux — Python 3.12.3, pytest-9.1.1, pluggy-1.6.0
仮想環境確認・poetry run・export（実測）
仮想環境確認・poetry run・export（実測）

poetry shell との違い

poetry shell はインタラクティブなシェルを起動して仮想環境に入ります。一方、poetry run <cmd> は仮想環境内で1コマンドだけ実行します。スクリプト実行や CI/CD では poetry run の方が扱いやすいです。

requirements.txt への書き出し（プラグイン必須）

ここはPoetry 2.x で一番詰まりやすいポイントです。poetry export コマンドは Poetry 2.x 以降は標準に含まれておらず、プラグインを別途インストールしないと動きません。




ubuntu@linuxlab: ~/sample-app
$ poetry export -f requirements.txt –without-hashes
The requested command export does not exist.
Documentation: https://python-poetry.org/docs/cli/

エラーが出ます。poetry-plugin-export をインストールします。




ubuntu@linuxlab: ~
$ pipx inject poetry poetry-plugin-export
injected package poetry-plugin-export into venv poetry
$ cd ~/sample-app
$ poetry export -f requirements.txt –without-hashes
certifi==2026.6.17 ; python_version >= “3.12”
charset-normalizer==3.4.7 ; python_version >= “3.12”
idna==3.18 ; python_version >= “3.12”
requests==2.34.2 ; python_version >= “3.12”
urllib3==2.7.0 ; python_version >= “3.12”
$ poetry export -f requirements.txt –without-hashes –with dev > requirements-dev.txt
（dev グループも含めて出力し、ファイルに保存）
poetry export と lock の実測ターミナル
poetry export と lock の実測ターミナル

注意: pip install 派との連携

poetry export で出力した requirements.txt は、Poetry を使っていない環境でも pip install -r requirements.txt で依存関係をインストールできます。Docker の本番イメージを pip で作りたい場合に便利です。

lock ファイルの管理

poetry.lock とは何か

poetry.lock は依存関係の全パッケージを特定バージョンに固定したファイルです。これをリポジトリにコミットしておくと、他のメンバーや CI でも全く同じバージョンがインストールされます。




ubuntu@linuxlab: ~/sample-app
$ head -5 poetry.lock
# This file is automatically @generated by Poetry 2.4.1 and should not be changed by hand.

[[package]]
name = “certifi”
version = “2026.6.17”

手順4：lock ファイルを再生成する

依存関係を最新にアップデートして lock ファイルを作り直す場合は poetry lock を実行します。




ubuntu@linuxlab: ~/sample-app
$ poetry lock
Updating dependencies
Resolving dependencies…
Writing lock file

Poetry 2.x での lock コマンドの変更点

  • poetry lock --check（lock が最新かチェック）は Poetry 2.x で廃止 → 代わりに poetry check を使う
  • poetry lock --no-update も廃止 → poetry lock だけで OK
  • lock ファイルの整合性は poetry install 実行時に自動検証される

poetry update でパッケージをアップデートする




ubuntu@linuxlab: ~/sample-app
$ poetry update requests
Updating dependencies
Resolving dependencies…
Writing lock file
$ poetry update
（全パッケージを pyproject.toml の制約範囲内でアップデート）

本番 vs 開発の使い分けパターン

依存グループ・仮想環境管理のターミナル
依存グループ・仮想環境管理のターミナル

依存グループを正しく使うと、本番環境に pytest や black などの開発ツールが紛れ込まないクリーンな状態を保てます。

手順5：本番環境へのインストール




ubuntu@linuxlab: ~/sample-app（本番サーバー）
$ poetry install –without dev
Installing dependencies from lock file
No dependencies to install or update
$ poetry show –only main
certifi 2026.6.17
charset-normalizer 3.4.7
idna 3.18
requests 2.34.2
urllib3 2.7.0

複数のグループを除外したい場合はカンマなしで繰り返します。




ubuntu@linuxlab: ~/sample-app
$ poetry install –without dev –without docs
Installing dependencies from lock file
場面 コマンド インストール対象
本番環境 poetry install --without dev main のみ
開発環境 poetry install 全グループ
テストのみ poetry install --only main --only test main + test グループ
CI環境 poetry install --without docs main + dev + test

Ubuntu 22.04 vs 24.04 比較

Ubuntu 22.04 vs 24.04 比較表（実測）
Ubuntu 22.04 vs 24.04 比較表（実測）

実際に両バージョンのコンテナで確認した結果です。

項目 Ubuntu 22.04 LTS Ubuntu 24.04 LTS
Python（apt デフォルト） Python 3.10.12 Python 3.12.3
pipx バージョン 1.1.0 1.4.3
Poetry（pipx install） 2.4.1 2.4.1
pip install poetry の動作 警告なしで実行可（非推奨） PEP 668 エラー → pipx 推奨
pyproject.toml 形式 [project] / PEP 621 [project] / PEP 621
poetry export プラグイン別途必要 プラグイン別途必要

Ubuntu 22.04 では警告なしに pip install poetry できますが、システムの Python 環境を壊すリスクがあるため、どちらのバージョンでも pipx 経由が安全です。

よくあるエラーと解決策

①「The requested command export does not exist.」

原因: Poetry 2.x は export コマンドをデフォルト非同梱にしました。

解決: pipx inject poetry poetry-plugin-export を一度実行する。

②「⚠️ ‘/root/.local/bin’ is not on your PATH」

原因: pipx install 後に PATH が設定されていない。

解決: pipx ensurepath を実行し、シェルを再起動する。




ubuntu@linuxlab: ~
$ pipx ensurepath
/home/ubuntu/.local/bin has been added to PATH in /home/ubuntu/.bashrc
Open a new terminal or run ‘source ~/.bashrc’
$ source ~/.bashrc
$ poetry –version
Poetry (version 2.4.1)

③「The option “–check” does not exist」

原因: poetry lock --check は Poetry 2.x で廃止されました。

解決: poetry check で代替できます。




ubuntu@linuxlab: ~/sample-app
$ poetry check
All set!

④「SolverProblemError: incompatible python constraints」

原因: pyproject.toml の requires-python と現在の Python バージョンが合わない。

解決: requires-python = ">=3.10" のように、使いたい Python バージョンを含む範囲に緩める。

まとめ

Ubuntu 24.04 LTS で Poetry 2.4.1 を使う際の要点を整理します。

  • インストールは pipx install poetry — Ubuntu 24.04 では pip install poetry は PEP 668 でブロックされる（実測確認）
  • pyproject.toml は PEP 621 形式（[project] セクション）に変わった
  • 依存グループは poetry add --group dev pytest → [dependency-groups] に記録される
  • 仮想環境をプロジェクト直下に置くなら poetry config virtualenvs.in-project true
  • poetry export は pipx inject poetry poetry-plugin-export で有効化
  • poetry lock --check は廃止 → poetry check で代替
  • 本番に開発ツールを含めない: poetry install --without dev

Poetry 1.x から 2.x への移行は書き方が変わっている部分が多く、古い記事そのままでは動かないコマンドがあります。特に poetry export の変更はハマりポイントでした。VPS に Python アプリをデプロイする際も、今回の依存グループの使い分けが役立ちます。


Vultr 公式サイトでプランを確認する →
著者アイコン
著者アイコン

Poetry 2.x は 1.x より書き方がスマートになったと思います。ただ、poetry export がデフォルトで使えなくなっていたのは正直気づかなかったです。Docker でインストールを試して初めてわかりました。VPS での Python アプリ運用にも今回の手順がそのまま使えます。

Poetryの基本（インストール・初回セットアップ）については も参考にしてください。

コメント

タイトルとURLをコピーしました