Apple Silicon Macへのasdfインストール・設定手順【2025年版】

はじめに

開発環境を構築する際、複数のプログラミング言語や異なるバージョンを管理することは日常的な作業です。asdfは、Ruby、Node.js、Python、Go、Erlang、Elixirなど、様々な言語とツールのバージョンを一つのコマンドラインツールで管理できる統合型バージョンマネージャーです。

Apple Silicon Mac（M1、M2、M3、M4チップ）の普及により、従来のツールが正しく動作しない問題が発生することがありましたが、2025年現在、asdfはネイティブでApple Siliconをサポートしており、安心して利用できます。

この記事では、Apple Silicon Macでのasdfのインストールからセットアップまでをステップバイステップで解説します。

Apple Silicon Macでの前提条件と重要な注意点

1. ターミナルがネイティブモードで動作していることを確認

まず最初に、お使いのターミナルがRosetta 2モードではなく、ネイティブモードで動作していることを確認します。

uname -m

出力がarm64であれば正常です。もしx86_64と表示される場合は、ターミナルがRosetta 2モードで動作している可能性があります。

Terminal.appの場合の修正方法：

1. ターミナルを終了
2. Finder → アプリケーション → ユーティリティ → Terminal.app
3. Terminal.appを右クリック → 「情報を見る」
4. 「Rossettaを使用して開く」のチェックを外す
5. ターミナルを再起動して uname -m で確認

2. 必要な開発ツールの確認

Apple Silicon Macでasdfを使用するには、以下のツールが必要です：

• Command Line Tools for Xcode または Xcode
• Homebrew（推奨インストール方法）
• Git

3. バージョン互換性について

一部の古いバージョンの言語（特にRuby 2.5.9以下）は、Apple Siliconでネイティブ実行できない場合があります。そのような場合のみRosetta 2の使用を検討してください。

ステップ1: Command Line Toolsのインストール

まず、開発に必要な基本ツールをインストールします。

xcode-select --install

すでにインストール済みの場合は以下のメッセージが表示されます：

xcode-select: error: command line tools are already installed

インストール状況を確認するには：

xcode-select -p

ステップ2: Homebrewのインストールと確認

asdfの推奨インストール方法はHomebrewです。Homebrewがインストールされていない場合は、まずインストールを行います。

Homebrewのインストール

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

Apple Silicon MacでのHomebrew確認

Apple Silicon Macでは、Homebrewは /opt/homebrew にインストールされます。正しくインストールされているか確認しましょう。

# Homebrewのバージョン確認
brew --version

# Homebrewのヘルスチェック
brew doctor

brew doctor の実行結果が Your system is ready to brew. と表示されれば準備完了です。

パスの設定確認

Apple Silicon MacでHomebrewを使用する場合、パスが正しく設定されているか確認します：

echo $PATH

/opt/homebrew/bin が含まれていることを確認してください。含まれていない場合は、シェルの設定ファイルに以下を追加します：

Zshの場合（macOS Catalina以降のデフォルト）:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bashの場合:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

ステップ3: 必要な依存関係のインストール

asdfとその後にインストールするプラグインに必要な依存関係をインストールします。

# asdfに必要な基本ツール
brew install coreutils git

# よく使用されるプラグインの依存関係（推奨）
brew install curl wget

Node.jsを管理する予定がある場合は、追加で以下をインストール：

brew install gpg gawk

Ruby管理を予定している場合は：

brew install openssl@3 readline libyaml zlib

Python管理を予定している場合は：

brew install openssl@3 xz zlib

ステップ4: asdfのインストール

いよいよasdfをインストールします。

brew install asdf

インストールが完了したら、バージョンを確認します：

asdf version

ステップ5: シェルの設定

asdfを使用するには、シェルの設定ファイルに設定を追加する必要があります。

Zsh（macOS Catalina以降のデフォルト）の設定

# ~/.zshrcにasdfの設定を追加
echo -e "\n# asdf configuration" >> ~/.zshrc
echo 'export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"' >> ~/.zshrc

# 補完機能を有効にする（オプション）
echo '. $(brew --prefix asdf)/libexec/asdf.sh' >> ~/.zshrc

Bash使用している場合

# ~/.bash_profileにasdfの設定を追加
echo -e "\n# asdf configuration" >> ~/.bash_profile
echo 'export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"' >> ~/.bash_profile

# 補完機能を有効にする（オプション）
echo '. $(brew --prefix asdf)/libexec/asdf.sh' >> ~/.bash_profile

設定の反映

設定を反映するためにターミナルを再起動するか、以下のコマンドを実行します：

# Zshの場合
source ~/.zshrc

# Bashの場合
source ~/.bash_profile

ステップ6: asdfの動作確認

設定が正しく行われているか確認します。

# asdfコマンドが利用可能か確認
which asdf

# asdfのヘルプを表示
asdf --help

# インストールされているプラグインを確認
asdf plugin list

ステップ7: 実際の使用例（Node.jsをインストール）

asdfの基本的な使い方を学ぶために、Node.jsをインストールしてみましょう。

プラグインの追加

# Node.jsプラグインを追加
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

# 利用可能なプラグインを確認
asdf plugin list

利用可能なバージョンの確認

# Node.jsのすべてのバージョンを表示
asdf list all nodejs

# 最新の安定版のみを表示
asdf list all nodejs | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | tail -5

Node.jsのインストール

# 最新版をインストール
asdf install nodejs latest

# 特定のバージョンをインストール（例：v20.10.0）
asdf install nodejs 20.10.0

バージョンの設定

# グローバル設定（全プロジェクトで使用）
asdf global nodejs latest

# ローカル設定（現在のディレクトリのみ）
asdf local nodejs 20.10.0

# 現在設定されているバージョンを確認
asdf current nodejs

動作確認

# Node.jsのバージョン確認
node --version

# npmのバージョン確認
npm --version

ステップ8: その他の言語のセットアップ例

Rubyのセットアップ

# プラグインの追加
asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git

# 最新版のインストール
asdf install ruby latest

# グローバル設定
asdf global ruby latest

Apple Silicon MacでのRuby注意点: Ruby 3.0以降はネイティブサポートされていますが、古いバージョン（特に2.6以下）では問題が発生する可能性があります。

Pythonのセットアップ

# プラグインの追加
asdf plugin add python

# 最新版のインストール
asdf install python latest

# グローバル設定
asdf global python latest

Goのセットアップ

# プラグインの追加
asdf plugin add golang https://github.com/asdf-community/asdf-golang.git

# 最新版のインストール
asdf install golang latest

# グローバル設定
asdf global golang latest

よくある問題と解決方法

問題1: command not found: asdf

原因: シェルの設定が正しくない、またはパスが通っていない

解決方法:

1. ターミナルを再起動
2. シェル設定ファイルを確認（ステップ5を再実行）
3. パスが正しく設定されているかを確認：echo $PATH

問題2: プラグインのインストールでエラーが発生

原因: 依存関係が不足している、またはApple Silicon特有の問題

解決方法:

# 依存関係の再インストール
brew update
brew upgrade
brew install <必要な依存関係>

# プラグインの再インストール
asdf plugin remove <言語名>
asdf plugin add <言語名>

問題3: 古いバージョンのRubyがインストールできない

原因: Apple Siliconでは古いRubyバージョンがネイティブサポートされていない

解決方法:

# 環境変数を設定してからインストール
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=/opt/homebrew/opt/openssl@3"
export RUBY_CFLAGS="-Wno-error=implicit-function-declaration"
asdf install ruby 2.7.8

問題4: ターミナルがRosettaモードで動作している

解決方法: ステップ1の「ターミナルがネイティブモードで動作していることを確認」を参照

便利なasdfコマンド一覧

# プラグイン関連
asdf plugin list                    # インストール済みプラグイン一覧
asdf plugin list all               # 利用可能なプラグイン一覧
asdf plugin add <言語名>            # プラグイン追加
asdf plugin remove <言語名>         # プラグイン削除

# バージョン管理
asdf list <言語名>                  # インストール済みバージョン一覧
asdf list all <言語名>              # 利用可能なバージョン一覧
asdf install <言語名> <バージョン>  # バージョンインストール
asdf uninstall <言語名> <バージョン> # バージョンアンインストール

# バージョン設定
asdf global <言語名> <バージョン>   # グローバル設定
asdf local <言語名> <バージョン>    # ローカル設定
asdf current                       # 現在の設定確認
asdf current <言語名>              # 特定言語の設定確認

# その他
asdf where <言語名>                # インストール場所確認
asdf which <コマンド名>            # 実行ファイルの場所確認
asdf reshim <言語名>               # shimの再生成

.tool-versionsファイルの活用

プロジェクトごとに使用する言語とバージョンを管理するには、.tool-versionsファイルを活用しましょう。

# プロジェクトディレクトリで
echo "nodejs 20.10.0" >> .tool-versions
echo "ruby 3.2.0" >> .tool-versions
echo "python 3.11.0" >> .tool-versions

# 設定されたバージョンを一括インストール
asdf install

.tool-versionsファイルの例：

nodejs 20.10.0
ruby 3.2.0
python 3.11.0
golang 1.21.0

まとめ

Apple Silicon Macでのasdfインストールとセットアップはこれで完了です！重要なポイントをまとめると：

1. ネイティブモードでの実行：Rosetta 2ではなくネイティブモードでの使用を心がける
2. Homebrewを活用：依存関係管理にHomebrewを活用する
3. 適切なシェル設定：パスと補完機能を正しく設定する
4. バージョン互換性：古いバージョンの言語では注意が必要

asdfを使えば、複数のプロジェクトで異なるバージョンの言語を簡単に管理できるようになります。チーム開発での環境統一や、異なるプロジェクト間の言語バージョン切り替えが格段に楽になるでしょう。

何か問題が発生した場合は、公式ドキュメント（https://asdf-vm.com/）も参照してください。Happy coding!