手順

最初に作業の全体像を載せます。
基本的には以下の手順で進めるとPoetryの環境構築が完了するはずです。（筆者の環境はM1Mac）

項番	内容	作業概要
1	pyenvのインストール	`brew install`
2	pyenvからPython環境のインストール	`install`
3	pyenvからインストールしたPython環境を使用する	`local/global`
4	Poetyrのインストール	`curl`
5	Poetyrプロジェクトを作成する	`init`
6	Poetryプロジェクトにライブラリを追加する	`add`
7	Poetryプロジェクトに指定されたライブラリをインストールする	`install`
8	Poetryプロジェクトの仮想環境に入る	`shell/source`

pyenv

pyenvのインストール

brew install pyenv

pyenvからPython環境のインストール

pyenv install 3.11.2

Pythonバージョン一覧方法

install可能なPythonバージョンの一覧

pyenv install -l
pyenv install --list

install済みのPythonバージョン一覧

pyenv versions

Tips of `Xcode Command Line Tools`

pyenv installを実行すると、たまに以下のエラーに遭遇する。

BUILD FAILED (OS X 12.6 using python-build 20180424)
configure: error: C compiler cannot create executables
See `config.log' for more details

これの原因として良くあるのが、Xcode Command Line Toolsがインストールされていないか、バージョンが古くなっているパターン。

消してから再度入れ直すとうまくいくことがある。

$ sudo rm -rf /Library/Developer/CommandLineTools
$ xcode-select --install

Ask ChatGPT to explain Xcode Command Line Tools.

Xcode Command Line Toolsとは、macOSで開発作業を行う際に利用する一連のツールとユーティリティのセットです。主に以下の目的で使用されます。

C, C++, Objective-C, Swiftなどの言語でのプログラムのコンパイルやデバッグ
ライブラリやフレームワークのインストール
システムツールやサービスの開発・管理
Xcode Command Line Toolsは、最初からMacには入っていません。ただし、開発作業を行うためには、通常XcodeやXcode Command Line Toolsをインストールする必要があります。

pyenv installコマンドに影響がある理由は以下の通りです。

Xcode Command Line Toolsは、C言語やその他の言語で書かれたプログラム（Pythonも含む）のコンパイルに使用されるコンパイラ（clang）を提供します。Pythonのインストールには、Pythonのソースコードをコンパイルする必要があるため、Xcode Command Line Toolsが必要です。
古いバージョンのXcode Command Line Toolsは、新しいmacOSバージョンや新しいPythonバージョンと互換性がない場合があります。そのため、古いバージョンのXcode Command Line Toolsがインストールされていると、pyenv installコマンドでエラーが発生することがあります。

pyenvからインストールしたPython環境を使用する

pyenv local <version>
pyenv global <version>

既存のPython環境からpyenvのPython環境に入り直す

pyenv install 3.X.Xやpyenv local 3.X.Xを実行しても、which pythonしてみると元々のPython環境のままになっていることがある。

その場合、以下のコマンドを~/.zshrcに追加し忘れていないかをチェックすると良い。
このコマンドはpyenvで作成した環境が正常に読み込まれるようにするもので、pyenv initと入力することでもガイドとして表示される。

export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

追加後source ~/.zshrcを実行してPythonの環境がpyenvに置き換わるっているか確かめる。

Poetry

Poetryのインストール

公式では以下のコマンドでのinstallが推奨されている。

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

他のインストール方法

（非推奨）Python環境があれば、pipでもインストールできる。

pip install poetry

非推奨の理由としては下記の点などが挙げられる。

pipがPoetryの依存関係を適切に解決できないことがあるため、正しく動作しない場合がある。
pip installを使用すると、既存のPython環境に影響を与える可能性がある。

Poetry自体のアップデート

以下のコマンドを実行する

poetry self update

Don't install in Anaconda Env. !!

Anacondaを使用していた場合、Anacondaの仮想環境の中でinstallしないように注意。Poetryの仮想環境内に入ろうとした時に下記のようなエラーが発生する。

Virtual environment already activated: /Users/<user_name>/opt/anaconda3/envs/<vertual_env_name>

Anacondaの仮想環境から抜ける

conda deactivate

Anacondaの仮想環境に自動で入らないようにする

conda config --set auto_activate_base False

Poetryプロジェクトを作成する

カレントディレクトリにpyproject.tomlを作成する。

poetry init

新規でディレクトリを作成して、そこからコードの記述を始めていく場合は、poetry newコマンドを実行する。
新規ディレクトリにpyproject.tomlが作成される。

poetry new <some_package>

Poetry Version 1.8.x ～の新機能：package-mode

Version1.8以上からは規定でpackage-modeがtrueになっています。普通にPythonの実行環境を作る意図であればfalseで問題ないためpyproject.tomlに以下のように1行追加しましょう。

pyproject.toml

[tool.poetry]
name = "any_project_name"
version = "0.1.0"
package-mode = false # ここを追加

`package-mode = true`の用途

というのもpakage-modeという名の通り、このプロジェクトをパッケージとして公開/配布したい場合などに使うと便利なオプションです。

配布する以外にも、例えば上記のpyproject.tomlで作成した仮想環境に入ると、そこではimport any_project_nameのように使用することができるようになります。

Poetryプロジェクトにライブラリを追加する

poetry add <package_name>

Python環境（.venvフォルダ）作成場所の指定

以下コマンドで、このプロジェクトで作成するPython環境をどこに置くかを設定できる。

poetry config virtualenvs.in-project true/false --local

true
- 格納場所：プロジェクトのルートディレクトリ
- このプロジェクトでのみ参照可能
false(default)
- 格納場所：~/Library/Caches/pypoetry/virtualenvs/
- どこからでも参照可能
--localオプション
- 指定すると、上記設定は現在のプロジェクトでのみに適応される
- 指定しない場合はすべてのプロジェクトでこの設定を引き継ぐ

現在のプロジェクトの設定を確認したいときは以下のコマンドを実行する。

poetry config virtualenvs.in-project

Poetryプロジェクトのライブラリをアップデートする

poetry updateコマンドでアップグレードする

poetry update <package_name>

updateコマンドでは`pyproject.toml`制約を超えるアップグレードはできないことに注意！

例えば以下のpyproject.tomlがある場合、poetry update openaiを実行しても、最新でopenai=0.27.xxまでのものにしかアップグレードできない。

キャレット要件：メジャー、マイナー、パッチという番号群のうち0でない最も左の数字を、新しいバージョン番号が更新しない場合に、更新が許可されます。

pyproject.toml

[tool.poetry.dependencies]
openai = "^0.27.0"

pyproject.tomlの制約内で、適合する最新バージョンにアップデートされる。
それ以上にアップグレードしたい場合は、pyproject.tomlを直接編集する方法がある。

`pyproject.toml`を直接編集してアップグレードする

まずは、以下例のようにpyproject.tomlを編集する

pyproject.tomlを編集する際にどのVersionを指定するか迷った際は、pypiのリリース履歴が参考になる

pyproject.toml

[tool.poetry.dependencies]
openai = "^0.27.0" # -> "^1.12.0"

その後以下のコマンドを実行する

$ poetry lock
$ poetry install

`poetry lock`コマンドの必要性

pyproject.tomlが更新されたとき：pyproject.tomlに新しい依存関係が追加されたり、既存の依存関係のバージョン範囲が変更された場合、poetry.lockファイルもそれに応じて更新する必要があります。これにより、新しい依存関係や更新されたバージョン範囲に対応する具体的なパッケージバージョンが確定します。

どのような時に実行する必要があるか、またはないか

必要な場合：
- pyproject.tomlで依存関係が追加・更新された後。
- プロジェクトを別の環境に移行するとき、依存関係の一貫性を保証したい場合。
必要ない場合：
- 既にpoetry.lockが最新であり、pyproject.tomlに変更がない場合。
- 単純なコードの変更や、依存関係に影響を与えないプロジェクトの設定を変更する場合。

Poetryプロジェクトに指定されたライブラリをインストールする

以下コマンドを実行することで、pyproject.tomlとpoetry.lock（あれば）を参照してライブラリのインストールが行われる。

poetry install

依存環境解決のためのPython環境

このpoetry installでの依存関係の解決には、poetry env infoでSystemの項目に記載されているPython環境が使用される。

|*･ω･)っ poetry env info

Virtualenv
Python:         3.11.2
Implementation: CPython
Path:           /Users/Ryku/Documents/sub_work/.venv
Executable:     /Users/Ryku/Documents/sub_work/.venv/bin/python
Valid:          True

System
Platform:   darwin
OS:         posix
Python:     3.11.2
Path:       /Users/Ryku/.pyenv/versions/3.11.2
Executable: /Users/Ryku/.pyenv/versions/3.11.2/bin/python3.11

Systemに記載されているPythonのVersionよりも新しいものをPoetryで構築するPythonのVersionに指定することはできない。

もし古いPython（例えば3.7等）がSystemに設定されていた場合は、以下のコマンド等を打つことでSystemのPython環境を変更できる。

$ poetry env use 3.10.10

もちろんここで指定するPython環境はすでにインストールされているのものでないとダメ。
先にpyenvを入れてpyenv install 3.10.10等を実行した後に上記コマンドを実行してPoetryのSystemに設定するのがおすすめ。

Poetryプロジェクトの仮想環境に入る

poetry shell

画像のようにユーザー名の左側に仮想環境名が表示されていれば成功。python hoge.pyと実行した際にその仮想環境で実行されるようになっている。

Tips of `poetry shell` vs `source`

以下コマンドでもPoetryが作成した仮想環境に入ることができる。poetry shellが意図した動作をしない場合は以下のコマンドを推奨。

# 直下の.venv環境に入る
source .venv/bin/activate

# ホームディレクトリ下の仮想環境に入る
 source /Users/<any_name>/Library/Caches/pypoetry/virtualenvs/<env_name>/bin/activate

Ask ChatGPT to explain What poetry shell is.

poetry shellは内部的に仮想環境のactivateスクリプトを実行しているのですが、それをサブプロセスで実行しているため、呼び出し元のシェルの環境に影響を与えません。ただし、sourceコマンドを使って明示的にactivateスクリプトを実行すると、呼び出し元のシェルの環境に影響を与えます。

poetry shellコマンドを実行すると、Poetryはプロジェクトに関連付けられた仮想環境を見つけます（存在しない場合は作成します）。
次に、Poetryは新しいサブプロセスを起動します。この新しいサブプロセスは、現在のシェルとは別の環境を持っています。
新しいサブプロセス内で、Poetryはactivateスクリプトを実行します。これにより、仮想環境のPythonインタープリタが使用されるようになります。
サブプロセスが終了すると、呼び出し元のシェルは元の状態に戻ります。
この仕組みのために、poetry shellは呼び出し元のシェル環境に影響を与えません。しかし、sourceコマンドを使って明示的にactivateスクリプトを実行すると、呼び出し元のシェル環境に仮想環境のPythonインタープリタへのパスが追加されるため、仮想環境を正しくアクティブにできます。

この問題は、シェルや環境変数の設定に依存することがあります。poetry shellが期待通りに動作しない場合は、sourceコマンドを使って仮想環境をアクティブにすることで、問題を回避できます。

VSCodeに仮想環境を認識させる

settings.jsonに以下の記述を追記します。
プロジェクト直下に.vscodeディレクトリを作成し、そのディレクトリ内に以下のファイルをおけば、プロジェクト内でのみ適用させることができます。

settings.json

{
    "python.defaultInterpreterPath": "/Users/<user_name>/Library/Caches/pypoetry/virtualenvs/<env_name>/bin/python"
}

Poetryプロジェクトの仮想環境から抜ける

新しい仮想環境に入りたい時は一回以下コマンドを挟む。

deactivate

仮想環境の出入りをせずに作成したpythonを使うこともできる

pyproject.tomlファイルが存在する場所でpoetry env info --pathコマンドを使用すると、作成したpython環境のパスが特定できる。仮に以下のような結果だったと仮定する。

$ poetry env info --path
/Users/ryku/Library/Caches/pypoetry/virtualenvs/apple-py3.11

このとき、以下のように実行すると、どこのディレクトリに居たとしても所望のpython環境を呼び出すことができる。

/Users/ryku/Library/Caches/pypoetry/virtualenvs/apple-py3.11/bin/python '実行したいファイル'

Poetryプロジェクトの仮想環境の削除

poetry env remove <vertual_env_name>

作成済み仮想環境一覧

poetry env list

手順

pyenv

pyenvのインストール

pyenvからPython環境のインストール

Pythonバージョン一覧方法

install可能なPythonバージョンの一覧

install済みのPythonバージョン一覧

Tips of Xcode Command Line Tools

Ask ChatGPT to explain Xcode Command Line Tools.

pyenvからインストールしたPython環境を使用する

既存のPython環境からpyenvのPython環境に入り直す

Poetry

Poetryのインストール

他のインストール方法

Poetry自体のアップデート

Don't install in Anaconda Env. !!

Poetryプロジェクトを作成する

Poetry Version 1.8.x ～ の新機能：package-mode

package-mode = trueの用途

Poetryプロジェクトにライブラリを追加する

Python環境（.venvフォルダ）作成場所の指定

Poetryプロジェクトのライブラリをアップデートする

poetry updateコマンドでアップグレードする

updateコマンドではpyproject.toml制約を超えるアップグレードはできないことに注意！

pyproject.tomlを直接編集してアップグレードする

poetry lockコマンドの必要性

どのような時に実行する必要があるか、またはないか

Poetryプロジェクトに指定されたライブラリをインストールする

依存環境解決のためのPython環境

Poetryプロジェクトの仮想環境に入る

Tips of poetry shell vs source

Ask ChatGPT to explain What poetry shell is.

VSCodeに仮想環境を認識させる

Poetryプロジェクトの仮想環境から抜ける

仮想環境の出入りをせずに作成したpythonを使うこともできる

Poetryプロジェクトの仮想環境の削除

作成済み仮想環境一覧

Tips of `Xcode Command Line Tools`

Poetry Version 1.8.x ～の新機能：package-mode

`package-mode = true`の用途

updateコマンドでは`pyproject.toml`制約を超えるアップグレードはできないことに注意！

`pyproject.toml`を直接編集してアップグレードする

`poetry lock`コマンドの必要性

Tips of `poetry shell` vs `source`