1. ホーム /
  2. 環境構築・運用 /
  3. asdfで始める開発環境構築：macOS & Ubuntu導入ガイド
  • 2025.10.23

asdfで始める開発環境構築：macOS & Ubuntu導入ガイド

開発環境の課題をasdfで解決

「新しいプロジェクトのたびに環境構築が大変」「言語のバージョン管理が複雑」「過去の環境設定を忘れてしまった」

複数のプログラミング言語やフレームワークを扱う開発において、環境構築は共通の課題です。プロジェクトごとに異なるバージョンを使い分けたり、新しい言語を試すたびに環境が複雑になることがあります。

これらの課題を解決するツールとして「asdf」があります。

asdfは、Node.js、Python、Rubyなど、様々な言語のバージョン管理を効率化するツールです。asdfを導入することで、環境構築の負担を軽減できます。

この記事では、asdfの基本的な概念から、macOSとUbuntuへの具体的な導入手順、そして導入後の最初のステップまでを解説します。

asdfを活用し、開発ワークフローを効率化しましょう！

目次

対象読者

  • 複数のプログラミング言語やツールを効率的に管理したい開発者
  • macOSまたはUbuntu環境でasdfの導入を検討している方
  • 開発環境構築の「もやもや」を解消したい方

1. asdfとは？asdfが必要とされる理由

asdfの主な特徴と利点

多様な言語・ツールの一元管理

  • プラグインシステムにより、Node.js、Python、Rubyだけでなく、Go、Java、PHP、Elixirなど、様々なプログラミング言語や開発ツールをasdfの統一されたコマンドで管理できます。
  • 新しいツールが登場した場合も、プラグインを追加することで対応可能です。

プロジェクトごとのバージョン自動切り替え

  • .tool-versionsファイルをプロジェクトルートに配置することで、プロジェクトに合わせた言語バージョンが自動的に適用されます。これにより、チーム開発における環境差異の問題を解消し、連携を円滑にします。

既存環境との高い互換性

  • nvmやpyenvなどの既存のバージョン管理ツールの設定ファイル（例: .nvmrc）との後方互換性があり、既存プロジェクトへの導入も容易です。
  • 主要なシェル（Bash, ZSH, Fish、Elvishなど）やGitHub Actionsにも対応しており、既存のワークフローに組み込むことができます。

2. macOSへのasdf導入手順

macOSユーザーの皆さんは、Homebrewを使うのが最も簡単です。

2.1. Homebrewを使ったインストール

  1. asdfのインストール:
    Homebrewを使ってasdfをインストールします。
brew install asdf
  1. シェルの設定:
    下記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

HomwBrewのインストールについては、以下の記事で詳細に解説していますので、是非ご覧ください。

【2025年版】macOS-Sequoia で Homebrew をインストールする方法｜初心者向け完全ガイド

2.2. Gitクローンを使ったインストール

Homebrewを使わない場合は、Gitクローンでasdfをインストールすることも可能です。

  1. 必要な依存関係のインストール:
    asdfをビルドするために必要な依存関係をインストールします。
brew install coreutils git bash
  1. Goのインストール (必要な場合):
    asdfをソースからビルドするにはGoが必要です。Goがインストールされていない場合は、Goの公式サイトを参考にインストールしてください。
  2. asdfのリポジトリをクローン:
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.18.0 # 最新の安定版ブランチを指定
  1. asdfのビルド:
    クローンしたディレクトリに移動し、asdfをビルドします。
cd ~/.asdf
make
  1. asdfバイナリの配置:
    ビルドされたasdfバイナリを、$PATHが通っているディレクトリ（例えば、/usr/local/bin）にコピーします。
sudo cp ./asdf /usr/local/bin
  1. PATHの確認:
    asdfが正しくPATHに設定されているかを確認します。
type -a asdf

出力の最初の行にasdfのインストールディレクトリが表示されていれば成功です。

  1. シェルの設定:
    上記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

2.3. プレビルドされたバイナリを使ったインストール

GitHub Releasesからasdfのプレビルドされたバイナリをダウンロードしてインストールする方法です。

  1. 必要な依存関係のインストール:
    asdfの実行に必要な依存関係をインストールします。
brew install coreutils git bash
  1. asdfバイナリのダウンロードと配置:
    asdfのGitHub Releasesページから、お使いのOSとアーキテクチャに合ったアーカイブをダウンロードします。
    ダウンロードしたアーカイブからasdfバイナリを抽出し、$PATHが通っているディレクトリ（例: /usr/local/bin）に配置します。
  2. PATHの確認:
    asdfが正しくPATHに設定されているかを確認します。
type -a asdf

出力の最初の行にasdfのインストールディレクトリが表示されていれば成功です。

  1. シェルの設定:
    下記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

2.4. Goを使ったインストール

Goがインストールされている環境で、go installコマンドを使ってasdfをインストールする方法です。

  1. 必要な依存関係のインストール:
    asdfの実行に必要な依存関係をインストールします。
brew install coreutils git bash
  1. Goのインストール:
    Goがインストールされていない場合は、Goの公式サイトを参考にインストールしてください。
  2. asdfのインストール:
    以下のコマンドを実行してasdfをインストールします。
go install github.com/asdf-vm/asdf/cmd/asdf@v0.18.0

これらの手順の後、asdfコマンドが利用可能になったか、以下のコマンドで確認してください。

asdf --version
  1. シェルの設定:
    下記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

asdfが実行できない場合

以下の手順でGoの環境変数GOPATHの値を確認および設定してください。

  1. GOPATHの確認:
go env GOPATH

このコマンドの出力が、asdfバイナリがインストールされたディレクトリです。

  1. PATHの確認:
    次に、そのディレクトリが$PATH環境変数に含まれているかを確認してください。
echo $PATH
  1. PATHへの追加 (必要な場合):
    もしgo env GOPATHで表示されたディレクトリ（または$HOME/go/bin）がecho $PATHの出力に含まれていない場合、以下のいずれかの方法で$PATHに追加してください。
  • Bashの場合: ~/.bash_profileまたは~/.bashrcに以下の行を追加します。
export PATH="$(go env GOPATH)/bin:$PATH"
# または
export PATH="$HOME/go/bin:$PATH"
  • Zshの場合: ~/.zshrcに以下の行を追加します。
export PATH="$(go env GOPATH)/bin:$PATH"
# または
export PATH="$HOME/go/bin:$PATH"

変更を反映させるために、シェルを再起動するか、sourceコマンドを実行してください。

2.5. asdfのシェルの設定

asdfをインストールした後、asdfが管理するツールをシステムが認識し、コマンドとして利用できるようにするためには、シェルの設定が必要です。

具体的には、asdfのshimパスを環境変数PATHに追加します。これにより、asdfでインストールした各言語のバージョンを切り替えたりできるようになります。

Bashの場合 (~/.bash_profile または ~/.bashrc に追記):

# asdf shimsをPATHに追加 (必須)
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Zshの場合 (~/.zshrc に追記):

# asdf shimsをPATHに追加 (必須)
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

設定を反映させるために、シェルを再起動するか、source ~/.bash_profile (または~/.bashrc、~/.zshrc) を実行します。

3. Ubuntuへのasdf導入手順

Ubuntuへの導入も、macOSと基本的な流れは同じです。

3.1. Gitクローンを使ったインストール

Ubuntuでは、Gitクローンでのインストールが一般的です。

  1. 必要な依存関係のインストール:
    asdfの実行に必要な最小限の依存関係をインストールします。
sudo apt update
sudo apt install git bash
  1. asdfのリポジトリをクローン:
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.18.0 # 最新の安定版ブランチを指定
  1. asdfのビルド:
    クローンしたディレクトリに移動し、asdfをビルドします。
cd ~/.asdf
make
  1. asdfバイナリの配置:
    ビルドされたasdfバイナリを、$PATHが通っているディレクトリ（例えば、/usr/local/bin）にコピーします。
sudo cp ./asdf /usr/local/bin
  1. PATHの確認:
    asdfが正しくPATHに設定されているかを確認します。
type -a asdf

出力の最初の行にasdfのインストールディレクトリが表示されていれば成功です。

  1. シェルの設定:
    上記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

asdfがビルドできない場合

asdfをビルドするにはmakeとGoが必要です。これらがインストールされていない場合は、以下の手順でインストールしてください。

  • makeのインストール:
    makeコマンドが見つからない場合は、以下のコマンドでインストールします。
sudo apt install make
  • Goのインストール:
    Goコンパイラが見つからない場合は、以下の手順でインストールします。
  1. Goのアーカイブをダウンロード:（ダウンロードサイト）
curl -LO https://go.dev/dl/go1.25.3.linux-arm64.tar.gz # 最新のバージョンとアーキテクチャに合わせてください
  1. アーカイブを解凍し、/usr/localに配置:
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.3.linux-arm64.tar.gz
  1. PATH環境変数を設定:
    ~/.bashrcまたは~/.zshrcに以下の行を追加してください。
export PATH=$PATH:/usr/local/go/bin

変更を反映させるために、シェルを再起動するか、source ~/.bashrc (またはsource ~/.zshrc) を実行してください。

  1. Goのインストールを確認:
go version

バージョン情報が表示されれば成功です。

3.2. プレビルドされたバイナリを使ったインストール

GitHub Releasesからasdfのプレビルドされたバイナリをダウンロードしてインストールする方法です。

  1. 必要な依存関係のインストール:
    asdfの実行に必要な最小限の依存関係をインストールします。
sudo apt update
sudo apt install git bash
  1. asdfバイナリのダウンロードと配置:
    asdfのGitHub Releasesページから、お使いのOSとアーキテクチャに合ったアーカイブをダウンロードします。
    ダウンロードしたアーカイブからasdfバイナリを抽出し、$PATHが通っているディレクトリ（例: /usr/local/bin）に配置します。
  2. PATHの確認:
    asdfが正しくPATHに設定されているかを確認します。
type -a asdf

出力の最初の行にasdfのインストールディレクトリが表示されていれば成功です。

  1. シェルの設定:
    上記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

3.3. Goを使ったインストール

Goがインストールされている環境で、go installコマンドを使ってasdfをインストールする方法です。

  1. 必要な依存関係のインストール:

asdfの実行に必要な最小限の依存関係をインストールします。

sudo apt update
sudo apt install git bash
  1. Goのインストール:
    Goがインストールされていない場合は、Goの公式サイトを参考にインストールしてください。
  2. asdfのインストール:

以下のコマンドを実行してasdfをインストールします。

go install github.com/asdf-vm/asdf/cmd/asdf@v0.18.0

これらの手順の後、asdfコマンドが利用可能になったか、以下のコマンドで確認してください。

asdf --version
  1. シェルの設定:
    上記「asdfのシェルの設定」を参照し、お使いのシェルに合わせて設定を行ってください。

4. 導入後の確認と最初のコマンド

asdfのインストールが完了したら、正しく動作するか確認しましょう。

  1. asdfのバージョン確認:
asdf --version

バージョン情報が表示されれば成功です。

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

asdfのプラグインによっては、追加の依存関係が必要になる場合があります。例えば、Node.jsプラグインをインストールする前に、以下の依存関係をインストールする必要があります。

Ubuntu (Debian) の場合:

sudo apt-get install dirmngr gpg curl gawk

CentOS/ Rocky Linux/ AlmaLinux の場合:

sudo yum install gnupg2 curl gawk

macOS の場合:

brew install gpg gawk
  1. 最初のプラグインを追加:
    試しにNode.jsプラグインを追加してみましょう。
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

これで、Node.jsのバージョン管理ができるようになりました。

  1. Node.jsのインストールと設定:
    最新の安定版Node.jsをインストールし、グローバルに設定します。
asdf install nodejs latest
asdf set nodejs latest

これで、node --version や npm --version がasdfで管理されたバージョンを表示するはずです。

5. バージョン定義ファイル (.tool-versions) の作成と追加

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 18.18.2 # 例として特定のバージョンを指定

これにより、現在のディレクトリに.tool-versionsファイルが作成され、nodejs 18.18.2のようなエントリが追加されます。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 18.18.2

まとめ：asdfで快適な開発ライフを！

asdfを導入することで、あなたは言語ごとのバージョン管理の煩わしさから解放され、より本質的な開発に集中できるようになります。macOSでもUbuntuでも、統一された操作感で複数の言語を管理できるasdfは、現代の開発者にとってまさに「次世代の開発環境」を築くための強力な味方となるでしょう。

さあ、今日からasdfを導入して、あなたの開発ワークフローを次のレベルへと引き上げましょう！

免責事項

本記事の情報は、公開時点での内容に基づいて作成されています。asdfや関連ツールのバージョンアップにより、手順や設定が変更される可能性があります。本記事の内容を参考に作業を行う際は、ご自身の責任において実施してください。いかなる損害が発生した場合でも、筆者は一切の責任を負いません。

Post Views: 10

SNSでもご購読できます。

コメントを残す

*