pyenvとpoetryでディレクトリ毎にPython環境を切り替える手順＋ノウハウまとめ

こんちには。

データアナリティクス事業本部 機械学習チームの中村です。

今回はローカル環境上でプロジェクト(ディレクトリ)ごとのPython環境を、pyenvとpoetryで良い感じに構築する方法を記事にしました。

はじめに

Python環境を構築する方法は、現在では様々な選択肢があります。

• Dockerで構築する
• Anacondaのenv createで仮想環境を構築する
• pyenvとpoetry環境で仮想環境を構築する

DockerはPythonのみならず様々な環境を独立して構築するのにとても有用ですが、使用するまでに多少ハードルが高い部分があります。

Anacondaもインストールされるライブラリが速度的にも優秀で便利ですが、pipでしかインストールできないパッケージも中には存在し、 conda installとpip installの共存に悩まされることも多いです。

そこで今回は、Dockerよりもライトに環境を切り替えることが可能で、パッケージの依存関係の解決も優秀なpyenv + poetryで環境構築する方法をご紹介します。

手順

まずpoetry単体では、各Pythonのパッケージはインストールできますが、おおもとのPythonバージョンを切り替えることはできません。 そこで、Pythonバージョンの切り替えをpyenvで、各パッケージをpoetryでインストールしていきます。

まずはpyenvのセットアップ

pyenvのインストール(Windowsの場合)

Windowsの場合、はじめにpipを実行できる環境が必要です。そもそもpipがない場合は以下からPythonをインストールします。(バージョンは何でもよいですが、新しい方が良いかと思います)

• https://www.python.org/

そしてPowerShell等から以下を実行して、pyenvを入れます。

pip install pyenv-win --target $env:USERPROFILE\.pyenv

さらに、PowerShellを管理者として起動して、以下を実行して環境変数を追加します。

[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PATH', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + $env:Path,"Machine")

権限周りで実行に失敗する場合は、PowerShellのExecutionPolicyの設定を見直す必要があります。

• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.2

pyenvのインストール(Macの場合)

Macの場合は、Homebrewでpyenvをインストールできます。

brew install pyenv
brew install pyenv-virtualenv

その後、環境変数を設定します。

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile

~/.zprofileの部分は、環境に応じてお使いのシェルに合うよう変更してください。

poetryのセットアップ

poetryインストール(Windowsの場合)

以下を実行します。

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

そして以下を環境変数PATHに追加します。

%APPDATA%\Python\Scripts

poetryインストール(Macの場合)

以下を実行します。

$ curl -sSL https://install.python-poetry.org | POETRY_HOME=/opt/poetry python - 
$ echo 'export PATH="/opt/poetry/bin:$PATH"' >> ~/.zprofile

~/.zprofileの部分は、環境に応じてお使いのシェルに合うよう変更してください。

poetryの設定確認

以下を実行すると設定を確認できます。

poetry config --list

初期設定では以下となっています。(Windowsの場合)

cache-dir = "C:\\Users\\{ユーザ名}\\AppData\\Local\\pypoetry\\Cache"
experimental.new-installer = true
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.path = "{cache-dir}\\virtualenvs"  # C:\Users\{ユーザ名}\AppData\Local\pypoetry\Cache\virtualenvs

設定を変更したい場合は、以下を実行します。

poetry config {設定名} {設定値}

プロジェクトごとの作業

使用したいPythonバージョンの取得

以下で使用可能なバージョン一覧を得ます。

pyenv install --list

今回は3.8の最新版である以下を選択して、インストールすることとします。

pyenv install 3.8.10

この段階で環境によっては（主にLinuxやMac）、別途依存するライブラリを入れるよう警告が出る場合がありますので、その場合は適切に対応してください。

ここからは、プロジェクトのディレクトリに移動し、そこでPython環境を初期セットアップしていきます。

pyenvでpythonバージョンを指定

フォルダ内に移動して以下を実行すると、Pythonのバージョンを指定することができます。

pyenv local 3.8.10

以下で、バージョンを念のため確認します。

python --version

poetryの初期化

フォルダ内で以下を実行して、環境を初期化します。 こちらはまだpyproject.tomlがフォルダに無い場合などの初回のみの実施でOKで、既にpyproject.tomlやpoetry.lockがある場合は実行不要です。

poetry init

色々は質問がコンソールで聞かれますが、基本はデフォルトで問題ありません。

実行後は、pyproject.tomlが作成されます。

poetry環境のインストール

以下を実行します。

poetry install

実行すると、pyproject.tomlやpoetry.lock(ある場合)を元に仮想環境が作成されます。 作成される場所は、poetryの設定に記載のあるcache-dirとなります。 キャッシュをクリアしたい場合は、ここにあるものをフォルダごと削除して、再度installしてください。

パッケージ(最新版)の追加

パッケージの追加は以下で行います。

poetry add {パッケージ名}

追加すると、poetry.lockやpyproject.tomlが更新されます。

その他のノウハウ

以上で基本的な流れは終わりですが、その他のノウハウをメモとして記載します。

インストール済みのPythonバージョン一覧確認

以下で確認することができます。

pyenv versions

出力は以下で、今のターミナルで選択されているものがどれなのかを確認することも可能です。

  3.6.8
* 3.8.10 (set by {プロジェクトのパス})
  3.9.1
  3.9.6

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

以下でglobalで使用することが可能です。

pyenv global 3.9.6

さきほどと同様に、pyenv versionで現在選ばれているものを確認することも可能です。

poetryの仮想環境をプロジェクトと同一フォルダに配置する

これをやるためには、poetryの設定を以下のように変更します。

poetry config virtualenvs.in-project true

これにより、プロジェクトは以下に.venvという名前で環境が作成されるようになります。

poetryの設定値をクリアする

設定値のクリアはunsetオプションで実施可能です。

poetry config {設定名} true

選択されているpoetry仮想環境の情報を取得する

以下で確認できます。

poetry env info

出力例は以下です。

Virtualenv
Python:         3.8.10
Implementation: CPython
Path:           C:\Users\{ユーザー名}\AppData\Local\pypoetry\Cache\virtualenvs\{仮想環境名}
Valid:          True

System
Platform: win32
OS:       nt
Python:   C:\Users\{ユーザー名}\.pyenv\pyenv-win\versions\3.8.10

パッケージのインストールをゼロから再度インストールやり直したい場合は、VirtualenvのPathにあるパッケージを削除すればOKです。

Python環境をglobal側から仮想環境側に切り替える

通常は、ターミナルの再起動やVSCodeの自動的な認識で、仮想環境側のPythonを使用してくれますが、ターミナルでcdしてきた場合などは、global側を参照してしまうケースもあります。 その場合は以下を実行すれば、仮想環境側に移動させることが可能です。

poetry shell

仮想環境側で何かしらのコマンドを実行する

先ほどと同様なケースですが、特定のコマンドを仮想環境側で実行したい場合は以下で実行させることが可能です。

poetry run {実行したいコマンド}

gitレポジトリからのパッケージ追加

pipと同じような形で、以下でインストールできます。

poetry add git+{レポジトリ名}

パッケージの削除

以下で可能です。

poetry remove {パッケージ名}

poetry自体のアップデート

以下でできるという話があります。

poetry self update

上記が失敗する場合(私の場合はそうでした)、普通にインストール時のコマンドを再度実行するのも一つです。

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

poetryの完全削除

以下を削除すればpoetry自体を削除できます。

• Windowsの場合
  • C:\Users\{ユーザ名}.poetry\bin
• Macの場合
  • ~/.poetry/bin

またキャッシュは別の場所にあるため、完全削除のためには以下も消してください。

• Windowsの場合
  • C:\Users\{ユーザ名}\AppData\Local\pypoetry
  • C:\Users\{ユーザ名}\AppData\Roaming\pypoetry
  • C:\Users\{ユーザ名}\AppData\Roaming\Python
• Macの場合
  • ~/Library/Application Support/pypoetry

キャッシュが原因でパッケージ追加時にエラーが発生する場合

以下のキャッシュのartifactsを削除してやり直すと成功する場合があります。

• Windowsの場合
  • C:\Users\{ユーザ名}\AppData\Local\pypoetry\Cache\artifacts
• Macの場合
  • ~/Library/Caches/pypoetry/artifacts

まとめ

いかがでしたでしょうか。

この記事がPython環境の構築で悩まれている方の参考になれば幸いです。

今後は、Dockerコンテナでやる場合についても別途記事にできたらと思います。