poetryのインストール・基本的な使い方

pythonの環境を管理するためのツールとしてpoetryを使用する．

開発環境はWSL Ubuntu-24.04を使用．

※ 2025/3/9:poetryのversion1.8.3から2.1.0への更新に対応(activate方法の変更，tomlファイルの構成変更)

install
初期設定確認
基本的な使い方

install

Introduction | Documentation | Poetry - Python dependency management and packaging made easy

Introduction Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries ...

# install
$ curl -sSL https://install.python-poetry.org | python3 -

# シェルに入り直すとパスが有効になっている
$ poetry --version
Poetry (version 1.8.3)

# バージョンを最新のものに更新したい場合
$ poetry self update
$ poetry --version
Poetry (version 2.1.1)

初期設定確認

virtualenvs.in-projectがtrueでない場合，仮想環境はcache-dirの中に作成される．

$ poetry config --list
cache-dir = "/home/haribote/.cache/pypoetry"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
keyring.enabled = true
solver.lazy-wheel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/haribote/.cache/pypoetry/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"
warnings.export = true

基本的な使い方

仮想環境の作成

poetry newとpoetry initコマンドがあるが，poetry initの方が以下の理由で使いやすい．

pyproject.tomlファイルのみが作成され，その他の余分なファイルが生成されない
対話形式で細かい設定ができる(モジュールの追加，pythonのバージョンなど)

$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [django_basic]:
Version [0.1.0]:
Description []:
Author [haribote-prog, n to skip]:
License []:
Compatible Python versions [^3.8]:  ^3.12

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Do you confirm generation? (yes/no) [yes] yes
$ ls
pyproject.toml

ただし，このままではpoetry installするときに以下のようなwarningが出てしまう．

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.
In a future version of Poetry this warning will become an error!

これはpoetryではデフォルトでpackageを作る設定になっていることによるものである．ここでは仮想環境を作るためだけに使うので，package-modeをfalseに設定する．

※ 2025/3/9追記:projectの設定は[project]の設定に移行されたため，[tool-poetry]は自分で追記する．

$ vi pyproject.toml

[tool.poetry]
name = "django-basic"
version = "0.1.0"
description = ""
authors = ["haribote-prog"]
readme = "README.md"
package-mode = false  # 設定を追加

[tool.poetry]
package-mode = false

モジュールの追加

poetry initをしたディレクトリ上でpoetry addコマンドを実行する．

$ poetry add django
The currently activated Python version 3.8.10 is not supported by the project (^3.12).
Trying to find and use a compatible version.
Using python3 (3.12.6)
Creating virtualenv django-basic-Nw3PIJnp-py3.12 in /home/haribote/.cache/pypoetry/virtualenvs
Using version ^5.1.2 for django

Updating dependencies
Resolving dependencies... (0.5s)

Package operations: 3 installs, 0 updates, 0 removals

  - Installing asgiref (3.8.1)
  - Installing sqlparse (0.5.1)
  - Installing django (5.1.2)

Writing lock file

poetryでは一つの仮想環境内で更に複数のグループに分けてインストールするモジュールを管理できる．

デフォルトではすべてmainグループにインストールされるが，開発環境用にしか使わないモジュールはdevグループとしてモジュールを追加することが推奨となる．後は必要に応じてtest用などを追加する．

poetry install時にはインストールするモジュールを指定できる．

$ poetry add jupyterlab --group dev

仮想環境のインストール

poetry initをしたディレクトリ上でpoetry installコマンドを実行する．

$ poetry install

仮想環境を使用する

特定のpythonコマンドだけを実行したいときはpoetry runを使うのが便利

# pythonコマンドやjupyter-labのコマンドが実行できる
$ poetry run python sample.py
$ poetry run jupyter-lab --no-browser

仮想環境をactivateしたい場合

$ eval $(poetry env activate)
# 仮想環境から抜ける場合
(django-basic-py3.12) $ deactivate

仮想環境を使用する (poetry 1.8.3時点のもの)

※ 2025/3/9:以下の情報は参考に残しておくが，最新のpoetryを使う場合は関係ない

仮想環境を使う方法は2通りある．

仮想環境用のサブシェルに入る(exitすると自動的に終了)
現在のシェルでactivateする(deactivateする)

仮想環境を有効化すると，デフォルトではプロンプトに仮想環境名が表示される．無効化したい場合は，$ export VIRTUAL_ENV_DISABLE_PROMPT=1を実行し，環境変数を設定しておく(元に戻したいときは$ export -n VIRTUAL_ENV_DISABLE_PROMPTを実行する)．

サブシェル：poetry shell

$ poetry shell
The currently activated Python version 3.8.10 is not supported by the project (^3.12).
Trying to find and use a compatible version.
Using python3 (3.12.6)
Spawning shell within /home/haribote/.cache/pypoetry/virtualenvs/django-basic-Nw3PIJnp-py3.12
$ . /home/haribote/.cache/pypoetry/virtualenvs/django-basic-Nw3PIJnp-py3.12/bin/activate
(django-basic-py3.12) $
(django-basic-py3.12) $ exit
exit
$

activate

$ source $(poetry env info --path)/bin/activate
(django-basic-py3.12) $
(django-basic-py3.12) $ deactivate
$

activateの方式で失敗する場合はpoetry envコマンドで設定を確認する．

$ source $(poetry env info --path)/bin/activatesource $(poetry env info --path)/bin/activate
-bash: /bin/activatesource: No such file or directory

$ poetry env info

Virtualenv
Python:         3.8.10
Implementation: CPython
Path:           NA
Executable:     NA

Base
Platform:   linux
OS:         posix
Python:     3.8.10
Path:       /usr
Executable: /usr/bin/python3.8

VirtualenvのPathがNAになっている場合は，以下コマンドで設定する(pythonのバージョンは各自の環境に合わせる)

$ poetry env use 3.12.6
Using virtualenv: /home/haribote/.cache/pypoetry/virtualenvs/django-basic-Nw3PIJnp-py3.12
$ poetry env info

Virtualenv
Python:         3.12.6
Implementation: CPython
Path:           /home/haribote/.cache/pypoetry/virtualenvs/django-basic-Nw3PIJnp-py3.12
Executable:     /home/haribote/.cache/pypoetry/virtualenvs/django-basic-Nw3PIJnp-py3.12/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.12.6
Path:       /usr/local
Executable: /usr/local/bin/python3.12