開発環境の「カオス」からの脱却
複数のプロジェクトを掛け持ちする開発者にとって、言語バージョンの管理は課題となりがちです。
例えば、あるプロジェクトではNode.jsのv18、別のプロジェクトではv20が必要だったり、Pythonも3.9と3.11を使い分けたりするケースがあります。
このような状況で、「環境が壊れた」「バージョン違いによるエラーが発生した」といった経験を持つ方もいるかもしれません。
従来のバージョン管理ツールは特定の言語に特化していることが多く、複数の言語を横断的に管理するのには限界がありました。
asdfは、このような開発環境の課題を解決するツールです。asdfを導入することで、言語のバージョン管理に費やす時間を減らし、開発業務に集中できます。
この記事では、asdfを使ってNode.js、Python、Rubyといった主要なプログラミング言語のバージョンを効率的に管理する方法を、具体的な手順を交えて解説します。
asdfが開発ワークフローをどのように改善するのか、その方法を見ていきましょう。
目次
- 1. asdfプラグインの追加方法：マルチ言語対応の第一歩
- 2. Node.jsのバージョン管理：プロジェクトに合わせた柔軟な切り替え
- 3. Pythonのバージョン管理：データサイエンスからWebまで
- 4. Rubyのバージョン管理：Webアプリケーション開発の強い味方
- 5. 複数の言語を同時に管理する際の注意点
- まとめ：asdfで開発の生産性を最大化する
- 免責事項
- 【付録】asdfプラグイン一覧（2025年10月時点）
対象読者
- 複数のプログラミング言語やツールを扱う開発者
- プロジェクトごとに異なるバージョンを使い分ける必要がある方
- 開発環境の構築・管理を効率化したい方
- asdfの基本的な使い方を学びたい方
1. asdfプラグインの追加方法：マルチ言語対応の第一歩
asdfの最大の強みは、そのプラグインによる拡張性です。
asdf本体は軽量なコア機能のみを提供し、各言語のバージョン管理は専用のプラグインによって行われます。これにより、必要な言語だけを柔軟に追加・管理できます。
1.1. asdf plugin add コマンドで言語を追加
新しい言語をasdfで管理するには、まずその言語のプラグインを追加します。コマンドは非常にシンプルです。
asdf plugin add <言語名>例えば、Node.jsを追加する場合は以下のようになります。
asdf plugin add nodejsこのコマンドを実行すると、asdfは指定された言語のプラグインをダウンロードし、asdfの管理下に置きます。
1.2. 利用可能なプラグインの検索
asdfがサポートしている言語やツールのプラグインは、以下のコマンドで確認できます。
asdf plugin list allこのコマンドを実行すると、利用可能なすべてのプラグインが一覧表示されます。膨大な数があるので、特定の言語を探す場合は grep などと組み合わせると便利です。
asdf plugin list all | grep pythonなお、記事の末尾には、asdfプラグインを以下のカテゴリに分類した一覧を掲載していますので、参考にしてください。
- プログラミング言語/ランタイム
- Web/フロントエンド開発
- バックエンド/API開発
- データベース/データ関連
- クラウド/インフラ/DevOps
- セキュリティ/認証
- テスト/品質
- ユーティリティ/CLIツール
2. Node.jsのバージョン管理：プロジェクトに合わせた柔軟な切り替え
Web開発で広く使われるNode.jsも、asdfで簡単にバージョン管理できます。
2.1. Node.jsプラグインの追加とバージョンインストール
Node.jsプラグインの追加
まずはNode.jsプラグインを追加します。
asdf plugin add nodejsインストール可能なバージョンの確認と絞り込み
次に、インストール可能なNode.jsのバージョンを確認します。
asdf list all nodejsasdf list all <言語名> の出力は非常に多いため、grep を使って特定のバージョンを絞り込むと便利です。例えば、Node.jsのv22系のみを表示したい場合は、以下のように実行します。
asdf list all nodejs | grep "22."特定のバージョンのインストール
特定のバージョンをインストールするには、以下のコマンドを使います。
asdf install nodejs <バージョン>例えば、Node.js v22.21.0をインストールする場合：
asdf install nodejs 22.21.02.2. グローバル/ローカルでのバージョン設定
asdfは、.tool-versionsファイルを使ってプロジェクトやグローバルな環境のバージョンを管理します。このファイルは、asdfがどのバージョンのツールを使用すべきかを判断するために参照されます。
グローバルなバージョン設定
すべてのディレクトリでデフォルトとして使用するバージョンを設定するには、$HOMEディレクトリでasdf setコマンドを使用します。
# Node.jsの最新バージョンをグローバルに設定
cd $HOME
asdf set nodejs latestこれにより、$HOME/.tool-versionsファイルにnodejs latestのようなエントリが追加されます。
プロジェクトごとのバージョン設定
特定のプロジェクトで異なるバージョンを使用したい場合は、プロジェクトのルートディレクトリでasdf setコマンドを使用します。
# 現在のディレクトリ（プロジェクトルート）にNode.jsの特定のバージョンを設定
asdf set nodejs 25.0.0 # 例として特定のバージョンを指定これにより、現在のディレクトリに.tool-versionsファイルが作成され、nodejs 25.0.0のようなエントリが追加されます。asdfは、現在のディレクトリから親ディレクトリへと.tool-versionsファイルを検索し、最初に見つかったものを適用します。
asdf set コマンドのオプション
asdf setコマンドには、.tool-versionsファイルの作成場所を制御するための便利なオプションがあります。
--homeまたは-u:
このオプションを使用すると、現在のディレクトリに関わらず、常に$HOME/.tool-versionsファイルにバージョンを設定できます。
# どのディレクトリからでもNode.jsの最新バージョンをグローバルに設定
asdf set --home nodejs latest--parentまたは-p:
このオプションを使用すると、現在のディレクトリから親ディレクトリを遡って、最も近い既存の.tool-versionsファイルにバージョンを設定できます。既存のファイルがない場合は、現在のディレクトリに新しいファイルが作成されます。
# 最も近い親ディレクトリの.tool-versionsファイルにNode.jsのバージョンを設定
asdf set --parent nodejs 22.21.03. Pythonのバージョン管理：データサイエンスからWebまで
Pythonもまた、asdfでバージョン管理することで、異なるプロジェクト要件に柔軟に対応できます。
3.1. Pythonプラグインの追加
Pythonプラグインを追加します。
asdf plugin add python https://github.com/asdf-community/asdf-python.gitシステム依存関係の確認とインストール
Pythonをasdfでインストールする前に、必要なシステム依存関係がインストールされていることを確認し、インストールすることが重要です。asdf-pythonは内部でpyenv python-buildを使用しており、Pythonのビルドには特定のライブラリやツールが必要です。
一般的な依存関係の例:
- Linux (Debian/Ubuntu系):
build-essential,libssl-dev,zlib1g-dev,libbz2-dev,libreadline-dev,libsqlite3-dev,wget,curl,llvm,libncurses5-dev,libncursesw5-dev,xz-utils,tk-dev,libffi-dev,liblzma-dev,git - macOS: Xcode Command Line Tools (
xcode-select --install)、Homebrewでインストールされる各種ライブラリ（openssl,readline,sqlite3,xz,tcl-tkなど）。
依存関係のインストール例:
- Ubuntuの場合:
sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev- macOSの場合:
xcode-select --install
brew install openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig詳細な依存関係やOSごとの具体的なインストール方法は、pyenvのSuggested build environment を参照してください。
3.2. 特定のバージョンのインストール
インストール可能なPythonのバージョンを確認します。
asdf list all python特定のバージョンをインストールします。
asdf install python <バージョン>例えば、Python 3.10.12をインストールする場合：
asdf install python 3.10.12ビルドオプションとトラブルシューティング
Pythonのビルド中に問題が発生した場合、pyenvのpython-buildのビルドオプションや、Common Build Problems Wiki が役立ちます。ビルドログを確認し、エラーメッセージに基づいて対処してください。
3.3. グローバル/ローカルでのバージョン設定
Pythonのバージョンも、Node.jsと同様にasdf setコマンドを使ってグローバルまたはプロジェクトローカルで設定できます。
グローバルなバージョン設定
すべてのディレクトリでデフォルトとして使用するPythonのバージョンを設定するには、$HOMEディレクトリでasdf setコマンドを使用します。
# Pythonの特定のバージョンをグローバルに設定
cd $HOME
asdf set python 3.9.18 # 例として特定のバージョンを指定これにより、$HOME/.tool-versionsファイルにpython 3.9.18のようなエントリが追加されます。
プロジェクトごとのバージョン設定
特定のプロジェクトで異なるPythonのバージョンを使用したい場合は、プロジェクトのルートディレクトリでasdf setコマンドを使用します。
# 現在のディレクトリ（プロジェクトルート）にPythonの特定のバージョンを設定
asdf set python 3.10.12 # 例として特定のバージョンを指定これにより、現在のディレクトリに.tool-versionsファイルが作成され、python 3.10.12のようなエントリが追加されます。asdfは、現在のディレクトリから親ディレクトリへと.tool-versionsファイルを検索し、最初に見つかったものを適用します。
asdf set コマンドのオプション
asdf setコマンドには、.tool-versionsファイルの作成場所を制御するための便利なオプションがあります。詳細については、「2.2. グローバル/ローカルでのバージョン設定」の「asdf set コマンドのオプション」を参照してください。
3.4. 複数のPythonバージョンの使用
asdfでは、複数のPythonバージョンを同時に設定し、必要に応じて自動的に切り替えることができます。これにより、異なるプロジェクトが要求するPythonバージョンに柔軟に対応できます。
.tool-versionsファイルに複数のバージョンが指定された場合、asdfは左から順に優先度を付けてバージョンを解決します。
asdf set -u python 3.10.12 3.9.18 systemasdf set -u python 3.10.12 3.9.18 systemの設定で、3.10.12`がインストールされていない場合、asdfは以下のように動作します。
3.10.12のスキップ: asdfはまず3.10.12を探しますが、インストールされていないためこれをスキップします。3.9.18の使用: 次に優先度の高い3.9.18がインストールされているかを確認します。もしインストールされていれば、pythonコマンドやpython3コマンドは3.9.18に解決されます。systemの使用: もし3.9.18もインストールされていない場合、asdfはsystemバージョンを使用します。これは、システムに元々インストールされているPythonのバージョンを指します。
この柔軟な設定により、例えば、あるプロジェクトでは最新のPython 3.10系で開発を進めつつ、別のプロジェクトでは特定のライブラリの互換性のためにPython 3.9系を使用するといった、プロジェクトごとの要件に合わせたPython環境の切り替えが容易になります。これにより、複数のプロジェクトを並行して開発する際のバージョン衝突を防ぎ、開発効率を大幅に向上させることができます。
asdfのバージョン管理に関する詳細は、公式ドキュメント を参照してください。
3.5. pipでインストールされたモジュールとバイナリ
ipythonのようなバイナリを持つモジュールをpipでインストールした場合、そのバイナリをパスに追加するためにasdf reshim pythonを実行する必要があります。
asdf reshim python3.6. デフォルトのPythonパッケージ
Pythonバージョンをインストールした直後に、pipでデフォルトのPythonパッケージセットを自動的にインストールできます。$HOME/.default-python-packagesファイルに1行に1つずつパッケージをリストアップします。
例: $HOME/.default-python-packages
ansible
pipenvこのファイルの場所は、ASDF_PYTHON_DEFAULT_PACKAGES_FILE環境変数で指定できます。
4. Rubyのバージョン管理：Webアプリケーション開発の強い味方
Ruby on RailsなどのWebアプリケーション開発で利用されるRubyも、asdfで効率的に管理できます。
4.1. Rubyプラグインの追加と依存関係
Rubyプラグインを追加する前に、必要な依存関係をインストールします。
macOSの場合（Homebrewを使用）:
# install Xcode Command Line Tools
xcode-select --install
# install dependencies with Homebrew
brew install openssl@3 readline libyaml gmp autoconfUbuntuの場合:
sudo apt-get update
apt-get install build-essential autoconf libssl-dev libyaml-dev zlib1g-dev libffi-dev libgmp-dev rustc詳細な依存関係やOSごとの具体的なインストール方法は、rbenvのSuggested build environment を参照してください。
依存関係のインストール後、Rubyプラグインを追加します。
asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git4.2. 特定のバージョンのインストール
インストール可能なRubyのバージョンを確認します。
asdf list all ruby特定のバージョンをインストールします。
asdf install ruby <バージョン>例えば、Ruby 3.2.2をインストールする場合：
asdf install ruby 3.2.24.3. グローバル/ローカルでのバージョン設定
Rubyのバージョンも、Node.jsやPythonと同様にasdf setコマンドを使ってグローバルまたはプロジェクトローカルで設定できます。
グローバルなバージョン設定
すべてのディレクトリでデフォルトとして使用するRubyのバージョンを設定するには、$HOMEディレクトリでasdf setコマンドを使用します。
# Rubyの特定のバージョンをグローバルに設定
cd $HOME
asdf set ruby 3.2.2 # 例として特定のバージョンを指定これにより、$HOME/.tool-versionsファイルにruby 3.2.2のようなエントリが追加されます。
プロジェクトごとのバージョン設定
特定のプロジェクトで異なるRubyのバージョンを使用したい場合は、プロジェクトのルートディレクトリでasdf setコマンドを使用します。
# 現在のディレクトリ（プロジェクトルート）にRubyの特定のバージョンを設定
asdf set ruby 3.1.4 # 例として特定のバージョンを指定これにより、現在のディレクトリに.tool-versionsファイルが作成され、ruby 3.1.4のようなエントリが追加されます。asdfは、現在のディレクトリから親ディレクトリへと.tool-versionsファイルを検索し、最初に見つかったものを適用します。
asdf set コマンドのオプション
asdf setコマンドには、.tool-versionsファイルの作成場所を制御するための便利なオプションがあります。詳細については、「2.2. グローバル/ローカルでのバージョン設定」の「asdf set コマンドのオプション」を参照してください。
5. 複数の言語を同時に管理する際の注意点
asdfは複数の言語をシームレスに管理できますが、いくつか注意すべき点があります。
5.1. .tool-versions ファイルの活用
複数の言語を扱うプロジェクトでは、.tool-versions ファイルを積極的に活用しましょう。
このファイルにプロジェクトで使用するすべての言語とそのバージョンを記述することで、チームメンバー間での環境の統一が容易になります。
# .tool-versions の例
nodjs 22.21.0
python 3.10.12
ruby 3.2.25.2. シェルの初期化とパスの設定
asdfが正しく動作するためには、シェルの設定ファイル（.bashrc, .zshrc など）にasdfの初期化スクリプトが記述されている必要があります。これにより、asdfが管理するツールのパスが正しく設定され、コマンドが実行できるようになります。
5.3. プラグインの競合と依存関係
ごく稀に、異なる言語のプラグイン間で競合が発生したり、特定のプラグインが他のツールに依存していたりする場合があります。問題が発生した場合は、asdfの公式ドキュメントや各プラグインのリポジトリを確認し、解決策を探しましょう。
まとめ：asdfで開発の生産性を最大化する
asdfは、複数のプログラミング言語やランタイムを扱う開発者にとって有用なツールです。
この記事で紹介したNode.js、Python、Rubyのバージョン管理方法を習得すれば、環境構築のトラブルを減らすことができます。
asdfを導入することで、あなたは以下のメリットを享受できます。
- 環境構築の簡素化: 新しいプロジェクトに参加する際も、
.tool-versionsファイル一つで必要な環境が整います。 - 開発効率の向上: 言語バージョンの切り替えがスムーズになり、複数のプロジェクトを効率的にこなせます。
- チーム開発の円滑化: チームメンバー全員が同じ開発環境を簡単に再現でき、バージョン違いによる問題を解消します。
asdfは継続的に改善されています。asdfを開発ワークフローに取り入れ、より効率的な開発体験を実現しましょう。
免責事項
本記事の情報は、公開時点での内容に基づいて作成されています。asdfや関連ツールのバージョンアップにより、手順や設定が変更される可能性があります。本記事の内容を参考に作業を行う際は、ご自身の責任において実施してください。いかなる損害が発生した場合でも、筆者は一切の責任を負いません。
【付録】asdfプラグイン一覧（2025年10月時点）
ここでは、主要なプラグインをカテゴリ別に分類して紹介します。なお、プラグインの最新情報は、Gitリポジトリを参照ください。
プログラミング言語/ランタイム
汎用言語
| プラグイン名 | 説明 |
|---|---|
| golang | Googleが開発したプログラミング言語Go |
| java | Java Development Kit (JDK)のバージョン管理 |
| nodejs | JavaScriptランタイム |
| perl | スクリプト言語 |
| php | Web開発で広く使われるスクリプト言語 |
| python | プログラミング言語Python |
| ruby | オブジェクト指向スクリプト言語 |
| rust | 高速で安全なシステムプログラミング言語 |
| zig | システムプログラミング言語 |
関数型言語
| プラグイン名 | 説明 |
|---|---|
| clojure | Lisp系言語Clojureのバージョン管理 |
| elixir | Erlang VM上で動作する関数型言語 |
| elm | Webフロントエンド向けの関数型言語 |
| erlang | 並行処理に強い関数型言語 |
| ghc | Haskellのコンパイラ |
| gleam | Erlang VM上で動作する型安全な言語 |
| lean | 証明支援システムLeanのバージョン管理 |
| lfe | Lisp Flavoured Erlang |
| opam | OCamlのパッケージマネージャー |
WebAssembly関連
| プラグイン名 | 説明 |
|---|---|
| bun | JavaScriptランタイム |
