asdf + poetry環境手順
asdf + Poetry 環境構築ガイド
この記事では、バージョン管理ツール「asdf」を用いて、Poetryを含むPython開発環境を構築する手順をまとめます。asdfは複数のプログラミング言語のバージョンを統一的に管理できるツールで、PythonやPoetryのバージョンを柔軟に切り替えることができます。
環境
- Ubuntu 24.04
- Windows WSL2
1. asdfのインストール
公式ガイドを参考にして、asdfをインストールします。
2. バイナリのダウンロードと配置
以下のコマンドを実行して、asdfのバイナリをダウンロード・解凍・配置します。
# バイナリのダウンロード
sudo curl -OL https://github.com/asdf-vm/asdf/releases/download/v0.16.4/asdf-v0.16.4-linux-amd64.tar.gz
# 配置先ディレクトリを作成
mkdir -p $HOME/bin
# アーカイブの展開
sudo tar -zxvf asdf-v0.16.4-linux-amd64.tar.gz -C $HOME/bin
# 圧縮ファイルの削除
sudo rm asdf-v0.16.4-linux-amd64.tar.gz
3. 環境変数の設定
asdfが正しく動作するよう、シェル設定ファイル（例：~/.bashrc）に以下の環境変数を追加します。
export PATH="$HOME/bin:$PATH"
export ASDF_DATA_DIR="$HOME/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"
設定を反映させるため、以下のコマンドを実行して再読み込みします。
source ~/.bashrc
4. asdfにおける言語環境のセットアップ
この章では、asdfで管理する言語環境（Python・Node.js）をセットアップする手順を説明します。
Python環境のセットアップ
Pythonモジュールをビルドする際に必要な依存パッケージが事前にインストールされていないと、インストールに失敗する場合があります。以下を参考に必要なパッケージをインストールしてください。
必要パッケージのインストール
sudo apt update;
sudo apt install build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
Pythonプラグインの追加とバージョンのインストール
# Pythonプラグインをasdfに追加
asdf plugin add python
# 利用可能なPythonバージョンを確認
asdf list all python
# Pythonの特定バージョンをインストール
asdf install python 3.12.9
asdf install python 3.13.2
# インストール済みバージョンの確認
asdf list python
Pythonバージョンの設定
# カレントディレクトリ用にバージョンを設定（.tool-versions ファイルが作成される）
asdf set python 3.12.9
# ホームディレクトリ全体で使用するバージョンを設定
asdf set --home python 3.12.9
# 現在の設定状況を確認
asdf current
python --version
Node.js環境のセットアップ
# Node.jsプラグインをasdfに追加
asdf plugin add nodejs
# 最新バージョンのNode.jsをインストール
asdf install nodejs latest
# バージョンを設定
asdf set nodejs latest
5. Poetryのセットアップとプロジェクト管理
PoetryはPythonの依存関係と仮想環境の管理を一元化するツールです。asdfによってPython環境を構築した後、Poetryを導入することで、より洗練された開発体験を実現できます。
Poetryのインストール
# Poetryのインストール
curl -sSL https://install.python-poetry.org | python3 -
# Poetryのパスをシェルに追加
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
インストール完了後、以下のコマンドでバージョンを確認できます。
poetry --version
Poetryプロジェクトの初期化と依存関係の管理
Poetryを利用したプロジェクトのセットアップにおいて、仮想環境をプロジェクト内に構築することは非常に便利で推奨されます。
仮想環境の構成（推奨）
デフォルトでは、Poetryは仮想環境をグローバルな場所に作成しますが、プロジェクトディレクトリ内に仮想環境を作成したい場合は以下の設定を行います。
poetry config virtualenvs.in-project true
この設定により、.venv/ ディレクトリがプロジェクトルートに作成され、環境管理が簡潔になります。
これにより pyproject.toml に次のようなセクションが追加されます。
[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
# 新規プロジェクトの初期化
poetry init
# 必要な依存パッケージの追加（例: pydantic）
poetry add pydantic@^2.10.0
# pyproject.tomlの構文チェック
poetry check
# 依存関係のインストールと更新
poetry install
poetry update
Poetry 2.0以降では
--no-devオプションは非推奨になっており、代わりに--without devを使用します。
# 開発依存を除外してインストールする例
poetry install --without dev --no-interaction
また、
[tool.poetry.dependencies]の代替として[project.dependencies]の使用が推奨されています。
[project]
dependencies = [
"pydantic>=2.10.0",
# 他の依存を列挙
]
パッケージディレクトリ構成によっては、
package-mode = falseを明示する必要があります。
[tool.poetry]
package-mode = false
6. 補足機能（オプション）
以下はPoetryの利用をさらに便利にするための追加機能です。
スクリプトの登録
Poetryでは、独自のスクリプトを pyproject.toml に記述することで、Poetry経由で実行可能にできます。
[tool.poetry.scripts]
my-script = "my_package.main:run"
# 実行例
poetry run my-script
依存関係のグループ分け（開発用など）
開発環境と本番環境で依存関係を分けることができます。
# 開発用の依存関係を追加
poetry add --group dev pytest
これにより、次のような設定が pyproject.toml に追加されます。
[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
.envファイルの活用
環境変数を管理するために .env ファイルを使用することができます。プロジェクトで python-dotenv を活用することで、Poetryと連携して設定情報を読み込むことが可能です。
# .env ファイル例
API_KEY=your-api-key
# Pythonコードでの読み込み
from dotenv import load_dotenv
load_dotenv()
Discussion