asdfでPythonをバージョン管理
· 約8分
Pythonのバージョン管理にasdfを使用することで、複数のPythonバージョンを簡単に管理できるようになりました。
asdfはPythonだけでなく、Node.js、Javaなど複数のランタイムを統一的に管理できる非常に便利なツールです。
以下の手順はasdf v0.18.0に基づいて説明します。
asdfとは
asdfは複数のプログラミング言語のランタイムバージョンを管理するためのツールです。pyenv、nvm、rbenvなどの個別のバージョン管理ツールを統一的に置き換えることができます。
主な利点：
- 複数の言語を一つのツールで管理
- プロジェクトごとのバージョン設定
- 豊富なプラグインエコシステム
asdfとvenvの違い
asdf: Pythonインタープリター自体のバージョン管理
- Python 3.11.7、3.12.1など異なるPythonバージョンを切り替え
venv: パッケージ（ライブラリ）の分離管理
- 同じPythonバージョンでもプロジェクトごとに異なるパッケージセットを使用
- 依存関係の競合を防ぐ
両方を組み合わせることで、Pythonバージョンとパッケージの両方を適切に管理できます。
asdfとvenvの違い
asdf: Pythonインタープリター自体のバージョン管理
- Python 3.11.7、3.12.1など異なるPythonバージョンを切り替え
venv: パッケージ（ライブラリ）の分離管理
- 同じPythonバージョンでもプロジェクトごとに異なるパッケージセットを使用
- 依存関係の競合を防ぐ
両方を組み合わせることで、Pythonバージョンとパッケージの両方を適切に管理できます。
asdfのインストール
macOSの場合
公式ガイドに従ってインストールします。
brew install asdf
zshの設定
~/.zshrcファイルに以下を追加：
# asdfの設定
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
export ASDF_DATA_DIR="$HOME/.asdf/data"
補完機能の設定
# 補完ディレクトリの作成
mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"
# zsh補完ファイルの生成
asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"
再度~/.zshrcに以下を追加：
# asdf補完の有効化
fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)
autoload -Uz compinit && compinit
設定を反映：
source ~/.zshrc
Pythonプラグインのインストールと設定
プラグインの追加
# Pythonプラグインを追加
asdf plugin add python
# インストール済みプラグインの確認
asdf plugin list
利用可能なPythonバージョンの確認
# インストール可能なPythonバージョンを表示
asdf list all python
Pythonのインストール
# 最新版をインストール
asdf install python latest
# 特定バージョンをインストール（例）
asdf install python 3.11.7
# インストール済みバージョンの確認
asdf list python
バージョンの設定
asdf v0.18.0ではasdf setコマンドを使用します：
# グローバル設定（HOMEフォルダ以下全体で使用）
asdf set --home python latest
# 現在の設定確認
asdf current python
出力例：
Name Version Source
python 3.13.5 /Users/username/.tool-versions
# Pythonコマンドの場所確認
which python3
出力例：
/Users/username/.asdf/data/shims/python3
プロジェクト固有の設定
プロジェクトディレクトリで特定のPythonバージョンを使用する場合：
# プロジェクトディレクトリに移動
cd /path/to/your/project
# プロジェクト用のPythonバージョンを設定
asdf set python 3.11.7
# .tool-versionsファイルが作成される
cat .tool-versions
出力例：
python 3.11.7
このファイルがあるディレクトリとその配下では、指定されたPythonバージョンが自動的に使用されます。
よく使うコマンド一覧
# 現在使用中のバージョン確認
asdf current
# 特定言語の現在バージョン
asdf current python
# インストール済みバージョン一覧
asdf list python
# 利用可能バージョン一覧（最新10件）
asdf list all python | tail -10
# プラグインの更新
asdf plugin update python
# 古いバージョンの削除
asdf uninstall python 3.10.0
トラブルシューティング
Pythonが見つからない場合
# shimの再作成
asdf reshim python
# パスの確認
echo $PATH | grep asdf
権限エラーが発生する場合
# asdfディレクトリの権限確認
ls -la ~/.asdf/
# 必要に応じて権限修正
chmod -R 755 ~/.asdf/
設定が反映されない場合
# .zshrcの再読み込み
source ~/.zshrc
# 現在のシェル設定確認
echo $ASDF_DATA_DIR
echo $PATH | grep asdf
実際の使用例
新しいプロジェクトでの設定
# プロジェクトディレクトリを作成
mkdir my-python-project
cd my-python-project
# プロジェクト用のPythonバージョンを指定
asdf set --local python 3.11.7
# 仮想環境の作成
python -m venv venv
source venv/bin/activate
# パッケージのインストール
pip install requests flask
チームでの.tool-versionsファイル共有
# .tool-versionsファイルをGitで共有
echo "python 3.11.7" > .tool-versions
echo "nodejs 18.19.0" >> .tool-versions
# チームメンバーは以下でバージョンをインストール
asdf install
設定が反映されない場合
# .zshrcの再読み込み
source ~/.zshrc
# 現在のシェル設定確認
echo $ASDF_DATA_DIR
echo $PATH | grep asdf
実際の使用例
新しいプロジェクトでの設定
# プロジェクトディレクトリを作成
mkdir my-python-project
cd my-python-project
# 1. asdfでPythonバージョンを指定（インタープリター管理）
asdf set python 3.11.7
# 2. venvで仮想環境を作成（パッケージ管理）
python -m venv venv
source venv/bin/activate
# 3. プロジェクト固有のパッケージをインストール
pip install requests flask
# 結果：Python 3.11.7 + 独立したパッケージ環境
なぜvenvも必要なのか？
問題：venvを使わない場合
# プロジェクトA
cd project-a
asdf set python 3.11.7
pip install django==4.2.0 requests==2.28.0
# プロジェクトB（同じPython 3.11.7）
cd ../project-b
pip install flask==2.3.0 requests==2.31.0 # ← requests 2.28.0が上書きされる
# プロジェクトAに戻ると...
cd ../project-a
# django が requests 2.31.0 で動作しない可能性！
解決：asdf + venv
# プロジェクトA: Python 3.11.7 + 独立した環境
project-a/ → django 4.2.0 + requests 2.28.0
# プロジェクトB: Python 3.11.7 + 独立した環境
project-b/ → flask 2.3.0 + requests 2.31.0
チームでの.tool-versionsファイル共有
# .tool-versionsファイルをGitで共有
echo "python 3.11.7" > .tool-versions
echo "nodejs 18.19.0" >> .tool-versions
# チームメンバーは以下でバージョンをインストール
asdf install
まとめ
asdfを使用することで以下のメリットが得られます：
- 統一的な管理: 複数の言語のバージョン管理を一つのツールで実現
- プロジェクト固有設定:
.tool-versionsファイルでプロジェクトごとの環境を管理 - 簡単な切り替え: コマンド一つでバージョン切り替えが可能
- チーム開発:
.tool-versionsファイルでチーム全体の環境を統一
Python開発での環境構築が大幅に簡素化されるため、特に複数のプロジェクトを扱う開発者にはぜひ活用していただきたいツールです。