手順
最初に作業の全体像を載せます。
基本的には以下の手順で進めると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
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 -
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プロジェクトにライブラリを追加する
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でない最も左の数字を、新しいバージョン番号が更新しない場合に、更新が許可されます。
[tool.poetry.dependencies]
openai = "^0.27.0"
pyproject.tomlの制約内で、適合する最新バージョンにアップデートされる。
それ以上にアップグレードしたい場合は、pyproject.tomlを直接編集する方法がある。
pyproject.tomlを直接編集してアップグレードする
まずは、以下例のようにpyproject.tomlを編集する
-
pyproject.tomlを編集する際にどのVersionを指定するか迷った際は、pypiのリリース履歴が参考になる
[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コマンドを使って仮想環境をアクティブにすることで、問題を回避できます。
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