Poetryを使ったPython仮想環境とパッケージ管理についてまとめてみた(第2回)

Poetryを使ったPythonの仮想環境とパッケージ管理について、自分なりに整理してみました。

第2回はasdf+Poetryの組み合わせによる環境構築の手順と、環境複製についてまとめます。

必要性や用語についてまとめた、第1回はこちら。

WSL2を使ったWindows環境での構築はこちら。

筆者環境

• MacBook Pro 13インチ M2 2022
• macOS Sonoma 14.3.1

asdf+Poetryによる環境構築

asdfをインストールし、asdfを介してPythonとPoetryをインストールする方針とします。

また、asdfによるインストールについては、globalやlocalなどには深く触れずに、フォルダ単位で｢.tool-versions｣を手動作成する方法で記載します。

手順概要

1. asdfのインストール
2. asdfへのPythonプラグインのインストール
3. asdfを介したPythonのインストール
4. asdfを介したPoetryのインストール
5. Poetryによる仮想環境の作成

※macOSにてx-codeコマンドラインツールとHomebrew、Visual Studio Code(VSCode)を使用しますので、事前にインストールしてください。

• x-codeコマンドラインツール

    xcode-select --install
  

• Homebrew

  brew.sh

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

• Visual Studio Code

  code.visualstudio.com

1. asdfのインストール

公式ドキュメントに沿って実施します。

記事執筆時点(2024/3/20)の情報で記載しているため、公式の最新情報をご確認ください。

asdf-vm.com

1. 依存関係のインストール

   asdfに必要なパッケージをインストールします。

    brew install coreutils curl git
   

2. asdfのダウンロード

   公式の推奨に準じて、gitでダウンロードを行います。

    git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
   

3. asdfのインストール

   今回はZSH+Gitの方法でインストールします。

   

   公式ドキュメントのZSH+Git用の説明

    . "$HOME/.asdf/asdf.sh"
   

    fpath=(${ASDF_DIR}/completions $fpath)
   

    autoload -Uz compinit && compinit
   

4. インストールの確認

   asdfのバージョン情報を表示して、asdfがインストールできていることを確認します。

    asdf version
   

   正常にインストールされている場合は、下記のように表示されます。

    v0.14.0-ccdd47d
   

2. asdfへのPythonプラグインのインストール

asdfでプログラミング言語などをインストールするためには、対応するプラグインのインストールが必要です。

まず、asdfを介してPythonをインストールしたいため、Pythonプラグインをインストールします。

こちらも、記事執筆時点の公式情報に準じて手順を記載しますので、適宜最新ドキュメントをご確認ください。

github.com

1. Pythonプラグインの依存関係のインストール

   macOS X の項を参照してbrewにてインストールします。

   github.com

    brew install openssl readline sqlite3 xz zlib tcl-tk
   

2. Pythonプラグインのインストール

    asdf plugin-add python
   

   これで、端末内に複数バージョンのPythonをインストールできるようになりました。

3. asdfを介したPythonのインストール

ここから、特定フォルダ(ディレクトリ)内でのみ、特定のPythonバージョンが使えるようにセットアップしていきます。

1. 作業用フォルダの作成

   任意の場所にフォルダを作成し、VSCodeで作成したフォルダを開きます。

   本記事では、｢asdf_poetry_demo｣というフォルダを作成しました。

   

   任意のフォルダを作成してVSCodeで開いた状態

2. インストール可能なPythonバージョンの確認

   VSCodeのターミナルを開き、asdfでインストール可能なPythonバージョンを確認します。

   用途に応じて、下記コマンドを参考に実行してください。

   • インストール可能なすべてのPythonバージョンの一覧を表示*1

       asdf list all python
     

     ※数が多いため、後述のgrepコマンドによる絞り込みや、安定の最新版のみ表示する形が実用的かもしれません。

   • インストール可能なPython3系のバージョンの一覧を表示(grepコマンドによる絞り込み)

       asdf list all python | grep ^3.
     

   • インストール可能なPythonバージョンの最新安定版を表示

       asdf latest python
     

3. asdfの設定ファイル｢.tool-versions｣の作成と、Pythonバージョンの記載

   ｢.tool-versions｣は、フォルダ内で利用するプログラミング言語などのバージョンを記載するファイルです。

   今回はPoetryもasdfを介してインストールするため、後の手順で同ファイルに追記します。

   VSCodeで作業フォルダ直下に｢.tool-versions｣という名前のファイルを新規作成し、前項で確認したインストールしたいPythonバージョンを記載して保存します。

   

   .tool-versionsを作成してPythonバージョンを記載

4. asdfによるPythonのインストール

   VSCodeのターミナルにて下記コマンドを実行すると、｢.tool-versions｣に記載したPythonがインストールされます。*2

    asdf install
   

5. 指定バージョンPythonのインストール確認

   ターミナルにてPythonバージョンを表示し、｢.tool-versions｣に記載したPythonがインストールされていることを確認します。

    python --version
   

4. asdfを介したPoetryのインストール

続いて、フォルダ(仮想環境)毎にパッケージを管理できるようにするため、Poetryをasdfを介してインストールします。

1. asdfへのPoetryプラグインのインストール

   Pythonと同じく、まずはasdfにPoetryのプラグインをインストールします。

   github.com

    asdf plugin-add poetry
   

2. インストール可能なPoetryバージョンの確認

   こちらもPythonと同じく、asdfのコマンドでインストール対象のバージョンを確認します。

   • インストール可能なPoetryのすべてのバージョンを表示

       asdf list all poetry
     

   • インストール可能なPoetryバージョンの最新安定版を表示

       asdf latest poetry
     

3. ｢.tool-versions｣へのPoetryバージョンの追記

   VSCodeで作業フォルダ内の｢.tool-versions｣を開き、インストールするPoetryのバージョンを記載して保存します。

   

   ｢.tool-versions｣へPoetryバージョンを追記

4. Poetryのインストール

   Pythonインストール時と同様に下記コマンドを実行します。

    asdf install
   

   ※Pythonはすでにインストールされているため、｢python 3.12.2 is already installed｣が表示されますが、問題ありません。

5. 指定バージョンPoetryのインストール確認

   下記コマンドで、｢.tool-versions｣に追記したPoetryバージョンが表示されることを確認します。

    poetry --version
   

これで、フォルダ単位でPythonと利用パッケージを管理するためのツールが揃いました。

5. Poetryによる仮想環境の作成

最後に、フォルダ単位で利用パッケージを隔離して管理できるよう、Poetryの初期設定を行います。

引き続き、作業フォルダを開いたVSCodeにて作業します。

1. 仮想環境の構築場所を作業フォルダ内に設定

   デフォルトでは仮想環境が作業フォルダ外に生成される*3ため、作業フォルダ内に仮想環境ができるよう設定を変更します。

    poetry config virtualenvs.in-project true --local
   

   コマンド実行後に｢poetry.toml｣ファイルが生成されるため、これを資源管理して共有･複製することで、他環境でも作業フォルダ内に仮想環境が生成されるようになります。

   

   生成されたpoetry.tomlファイル

2. Poetry設定ファイルの生成と編集

   Poetryの設定ファイル｢pyproject.toml｣を作業ディレクトリ内に生成し、必要に応じて内容を編集します。

   このファイルの中にPoetryを介してインストールしたパッケージとバージョン指定の情報が追記されます。*4

    poetry init -n
   

   

   生成されたpyproject.tomlファイル

   最低限、｢pyptoject.toml｣に記載されいているPythonバージョンが正しいことを確認してください。

   また、Readme.mdが存在しない場合はエラーとなる場合があるため、作業フォルダ内に同名のファイルを作成しておくとよいでしょう。*5

3. Poetryが使用するPythonの指定

   asdfでインストールしたPythonがPoetryで利用されるように設定を変更します。

   • Pythonのパスを確認(コピーしておく)

       which python
     

   • Poetryで使用するPythonを設定

       poetry env use {確認したPythonのパスを記載}
     

コマンド実行後に｢.venv｣というフォルダが作業ディレクトリ内に作成されますが、これが仮想環境です。

Poetryにより自動生成された仮想環境(.venvフォルダ)

このフォルダ内に、作業フォルダでPoetryを通してインストールしたパッケージの実体などが追加されていきます。

｢.venv｣フォルダ内はPoetryにより自動生成･更新されるため、何もする必要はありません。

これで、asdfとPoetryによる環境構築が完了しました。

Poetryの基本操作と設定ファイル

仮想環境でのPythonスクリプトの実行

poetry runコマンドで、仮想環境内でのコマンド実行となります。*6

poetry run python sample.py

Pythonパッケージの追加と削除

• パッケージ追加(requestsを追加)

    poetry add requests
  

  追加したパッケージは｢pyproject.toml｣に追記され、依存関係も一緒にインストールされます。

  

  requestsパッケージの｢pyproject.toml｣への追記

  

  requests追加時の依存関係インストール(ターミナルでの表示)

  また、正確な依存関係が記載された｢poetry.lock｣ファイルも生成(すでにある場合は更新)されます。

  このファイルは依存関係解決後の確定したバージョンが記載されているため、環境複製時にpyproject.tomlと合わせて利用することで、複製元と同じ環境が構築できます(後述)。

  

  poetry addコマンドで自動生成された｢poetry.lock｣ファイル

• パッケージ削除

    poetry remove requests
  

asdf+Poetryによる環境複製

複製先で必要なセットアップ

• asdfとPoetryのインストール

複製先に共有が必要なファイル

作業フォルダの下記のみ共有します。

• ソースコード本体
• .tool-versions
• pyproject.toml
• poetry.lock
• poetry.toml

複製手順

1. 複製先に共有が必要なファイルの格納 同一フォルダ内に格納します。すでにフォルダに一式格納されている場合は不要です。

2. pythonとPoetryのインストール 複製元から共有されたファイル一式が格納されたフォルダ内で下記コマンドを実行します。

    asdf install
   

3. 依存関係のインストール 前項に引き続き、下記コマンドを実行します。*7

    poetry install --no-root
   

補足資料

asdfおよびPoetryの設定やコマンドの詳細は、公式ドキュメントをご覧ください。

asdf

asdf-vm.com

asdf-vm.com

Poetry

python-poetry.org

python-poetry.org

*1:表示された一覧をご覧いただけばわかると思われますが、anacondaなどもasdfでインストール可能です。

*2:｢.tool-versions｣に記載したパッケージをすべてインストールするコマンドです。

*3:poetry config --listで設定の一覧が確認でき、virtualenvs.pathに仮想環境の構築場所が記載されています

*4:-nはオプションで、外すと対話形式でpyptoject.tomlが生成できます。

*5:Readme.mdは、マークダウン記法でプロジェクト(プログラム)の説明や使い方などの基本情報を記載するためのファイルです。

*6:正確には、venvのactivateとdeactivateを自動で実行しています。

*7:--no-rootはオプションで、依存関係のみインストールします。