はじめよう

asdfのインストールには次の手順が必要です:

1. 依存関係のインストール
2. asdfコアのダウンロード
3. asdfのインストール
4. 管理したいツール/ランタイムごとにプラグインをインストール
5. ツール/ランタイムの特定バージョンをインストール
6. .tool-versionsファイルで、グローバルまたはプロジェクトのバージョンをセット

1. 依存関係のインストール

asdfの動作にはgitおよびcurlが必要です。以下の表は、 あなたが使用している パッケージマネージャで実行するコマンドの 一部例 です(いくつかのツールは、後の手順で自動的にインストールされます)。

OS	パッケージマネージャ	コマンド
linux	Aptitude	apt install curl git
linux	DNF	dnf install curl git
linux	Pacman	pacman -S curl git
linux	Zypper	zypper install curl git
macOS	Homebrew	brew install coreutils curl git
macOS	Spack	spack install coreutils curl git

備考

お使いのシステムの構成によっては、接頭にsudoが必要となる場合もあります。

2. asdfのダウンロード

公式ダウンロード

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

コミュニティがサポートするダウンロード方法

理由がない限り、gitコマンドを使用した公式ダウンロードの手順を使用することを強く推奨します。

方法	コマンド
Homebrew	brew install asdf
Pacman	git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si または好みのAURヘルパーを使用

3. asdfのインストール

あなたが使用しているシェル、OS、およびインストール方法によって、ここでの設定方法が変わります。最も適したものを選択してください。

masOSユーザの方は、この節の最後にあるpath_helperに関する警告を必ず参照してください。

Bash & Git

~/.bashrcに下記の行を追記します:

. "$HOME/.asdf/asdf.sh"

コマンド補完が必要な場合は、.bashrcに下記の行を追記します:

. "$HOME/.asdf/completions/asdf.bash"

Bash & Git (macOS)

macOS Catalina以降を使用している場合、デフォルトのシェルはZSHです。Bashに変更していない限り、ZSHの手順を参照してください。

~/.bash_profileに下記の行を追記します:

. "$HOME/.asdf/asdf.sh"

コマンド補完が必要な場合は、.bash_profileに下記の行を追記します:

. "$HOME/.asdf/completions/asdf.bash"

Bash & Homebrew

下記コマンドで、~/.bashrcにasdf.shを追加します:

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc

コマンド補完が必要な場合は、Homebrewのガイドに従って設定を完了させるか、下記コマンドを実行します:

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc

Bash & Homebrew (macOS)

macOS Catalina以降を使用している場合、デフォルトのシェルはZSHです。Bashに変更していない限り、ZSHの手順を参照してください。

下記コマンドで、~/.bash_profileにasdf.shを追加します:

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile

コマンド補完が必要な場合は、Homebrewのガイドに従って設定を完了させるか、下記コマンドを実行します:

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile

Bash & Pacman

~/.bashrcに下記の行を追記します:

. /opt/asdf-vm/asdf.sh

コマンド補完が必要な場合は、bash-completionをインストールします。

Fish & Git

~/.config/fish/config.fishに下記の行を追記します:

source ~/.asdf/asdf.fish

コマンド補完が必要な場合は、下記コマンドを実行します:

mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions

Fish & Homebrew

下記コマンドで、~/.config/fish/config.fishにasdf.shを追加します:

echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish

コマンド補完は、Fish shellのHomebrewが担います。親切ですね!

Fish & Pacman

~/.config/fish/config.fishに下記の行を追記します:

source /opt/asdf-vm/asdf.fish

コマンド補完は、AURパッケージのインストール時に自動的に設定されます。

Elvish & Git

下記コマンドで、~/.config/elvish/rc.elvにasdf.elvを追加します:

mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

コマンド補完は自動的に設定されます。

Elvish & Homebrew

下記コマンドで、~/.config/elvish/rc.elvにasdf.elvを追加します:

mkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

コマンド補完は自動的に設定されます。

Elvish & Pacman

下記コマンドで、~/.config/elvish/rc.elvにasdf.elvを追加します:

mkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

コマンド補完は自動的に設定されます。

ZSH & Git

~/.zshrcに下記の行を追記します:

. "$HOME/.asdf/asdf.sh"

または、asdf for oh-my-zshのようなZSHフレームワークプラグインを使用して、このスクリプトをsourceし、コマンド補完をセットアップします。

コマンド補完は、ZSHフレームワークのasdfプラグインで設定するか、~/.zshrcに下記の行を追記することで設定できます:

# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit

• compinitのセットアップをカスタマイズしている場合は、asdf.shソース以下にcompinitがくるようにしてください。
• ZSHフレームワークでcompinitのセットアップをカスタマイズしている場合は、フレームワークソース以下にcompinitがくるようにしてください。

警告

ZSHフレームワークを使用している場合、新しいZSHコマンド補完を使用するには、fpath経由で、関連するasdfプラグインの更新が必要となることがあります。Oh-My-ZSH asdfプラグインは、ohmyzsh/ohmyzsh#8837でご覧いただくと分かるとおり、まだ更新されていません。

ZSH & Homebrew

下記コマンドで、~/.zshrcにasdf.shを追加します:

echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

OR use a ZSH Framework plugin like asdf for oh-my-zsh which will source this script and setup completions.

コマンド補完は、ZSHフレームワークasdfによって設定されるか、Homebrewの説明に従って設定必要があります。ZSHフレームワークを使用している場合、新しいZSHコマンド補完を使用するには、fpath経由で、関連するasdfプラグインの更新が必要となることがあります。Oh-My-ZSH asdfプラグインは、ohmyzsh/ohmyzsh#8837でご覧いただくと分かるとおり、まだ更新されていません。

ZSH & Pacman

~/.zshrcに下記の行を追記します:

. /opt/asdf-vm/asdf.sh

コマンド補完は、ZSHに適した場所に配置されますが、オートコンプリートを使用するようにZSHを設定する必要があります。

PowerShell Core & Git

~/.config/powershell/profile.ps1に下記の行を追記します:

. "$HOME/.asdf/asdf.ps1"

PowerShell Core & Homebrew

下記コマンドで、~/.config/powershell/profile.ps1にasdf.shを追加します:

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1

PowerShell Core & Pacman

~/.config/powershell/profile.ps1に下記の行を追記します:

. /opt/asdf-vm/asdf.ps1

Nushell & Git

下記コマンドで、~/.config/nushell/config.nuにasdf.nuを追加します:

"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path

コマンド補完は自動的に設定されます。

Nushell & Homebrew

下記コマンドで、~/.config/nushell/config.nuにasdf.nuを追加します:

"\n$env.ASDF_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " +  (brew --prefix asdf | str trim | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path

コマンド補完は自動的に設定されます。

Nushell & Pacman

下記コマンドで、~/.config/nushell/config.nuにasdf.nuを追加します:

"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path

コマンド補完は自動的に設定されます。

POSIX Shell & Git

~/.profileに下記の行を追記します:

export ASDF_DIR="$HOME/.asdf"
. "$HOME/.asdf/asdf.sh"

POSIX Shell & Homebrew

下記コマンドで、~/.profileにasdf.shを追加します:

echo -e "\nexport ASDF_DIR=\"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile
echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile

POSIX Shell & Pacman

~/.profileに下記の行を追記します:

export ASDF_DIR="/opt/asdf-vm"
. /opt/asdf-vm/asdf.sh

asdfのスクリプトは、$PATHを設定したあと、かつ、使用中のフレームワーク(oh-my-zsh など)を呼び出したあとに記述する必要があります。

警告

macOSでは、BashまたはZSHシェルを起動すると、自動的にpath_helperというユーティリティが呼び出されます。path_helperはPATH(およびMANPATH)内の項目の順番を並び替えることができるため、特定の順序を必要とするツールの動作に、一貫性が無くなってしまいます。これを回避するため、macOSでasdfを利用するときは、強制的にPATHエントリの先頭に追加する(優先度を一番高くする)ようにしてください。これは、ASDF_FORCE_PREPEND環境変数で制御できます。

PATHの変更を反映するために、シェルを再起動してください。たいていの場合、ターミナルのタブを新たに開けばOKです。

コアのインストールが完了!

これで、asdfのコアのインストールは完了です🎉

しかし、asdfが役に立つようになるのは、プラグインをインストールしてからツールをインストールし、バージョンを管理するようになってからです。引き続き、ガイドを進めていきましょう。

4. プラグインのインストール

ここではデモとして、asdf-nodejsプラグインを使用してNode.jsをインストール・設定してみましょう。

プラグインの依存関係

各プラグインには依存関係があるため、プラグインのリポジトリを確認しておきましょう。asdf-nodejsの場合、必要なものは次のとおりです:

OS	依存関係インストールコマンド
Debian	apt-get install dirmngr gpg curl gawk
CentOS/ Rocky Linux/ AlmaLinux	yum install gnupg2 curl gawk
macOS	brew install gpg gawk

一部のプラグインではインストール後の事後処理でこれらの依存関係が必要となるため、あらかじめインストールしておきましょう。

プラグインのインストール

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

5. 特定のバージョンのインストール

Node.js用のプラグインをインストールしたので、このツールの特定のバージョンをインストールしましょう。

インストール可能なバージョンはasdf list all nodejsコマンドで確認できますし、特定のメジャーバージョンのサブセットはasdf list all nodejs 14コマンドで確認できます。

最新版をインストールするには、次のコマンドを実行します:

asdf install nodejs latest

備考

asdfでは正確なバージョン番号を指定してください。latestは、現時点での最新バージョンを指定できるasdfのヘルパーです。

6. バージョンをセット

asdfは、カレントディレクトリから上位の$HOMEディレクトリまでに存在するすべての.tool-versionsファイルをもとに、ツールのバージョンを照会します。照会は、asdfで管理するツールを実行した際に、ジャストインタイムで行われます。

警告

ツールで指定されたバージョンが見つからない場合、エラーが発生します。asdf currentコマンドを実行すると、カレントディレクトリにおいてツールのバージョンを解決可能か確認できるため、どのツールが実行に失敗するか検証することができます。

グローバル

グローバルのデフォルト設定は、$HOME/.tool-versionsで管理されます。グローバルのバージョンをセットするには、次のコマンドを実行します:

asdf global nodejs latest

すると、$HOME/.tool-versions内には次のように書き込まれます:

nodejs 16.5.0

一部のOSでは、pythonのように、asdfではなくシステムが管理するツールが既にインストールされていることがあります。それを使用する場合、asdfに対して、バージョン管理をシステムに委任するように指示する必要があります。詳しくは、バージョンのリファレンスをご覧ください。

ローカル

ローカルのバージョン設定は、$PWD/.tool-versionsファイル(カレントディレクトリ内)で定義されます。たいていの場合は、プロジェクトのGitリポジトリ内となるでしょう。対象となるディレクトリで、下記コマンドを実行します:

asdf local nodejs latest

すると、$PWD/.tool-versions内には次のように書き込まれます:

nodejs 16.5.0

ツールごとに用意された既存バージョンファイルの利用

asdfは、他のバージョンマネージャ向けに作られた既存のバージョンファイル(例: rbenvの場合は.ruby-versionファイル)からの移行をサポートしています。これはプラグイン単位でのサポートです。

asdf-nodejsであれば、.nvmrcファイルと.node-versionファイルの両方に対応しています。このサポートを有効にするには、asdfの構成設定ファイルである$HOME/.asdfrc内に、下記の行を追記してください:

legacy_version_file = yes

構成設定でのその他のオプションについて詳しくは、構成設定のリファレンスをご覧ください。

入門完了!

以上で、asdfの入門は完了です🎉 ここまでで、プロジェクトでのnodejsのバージョン管理ができるようになりました。プロジェクトで使用するツールごとに、同様の手順を実施してください!

asdfには使いこなすと便利なコマンドが他にもいっぱいあり、asdf --helpコマンドまたは単にasdfコマンドを実行すれば、すべてのコマンドの説明を見ることができます。コマンドは大きく分けて3つのカテゴリに分けられます:

• asdfのコア
• プラグイン
• ツールのバージョン