はじめよう

1. asdfのインストール

asdfはいくつかの方法でインストールできます:

パッケージマネージャーを使用 - 推奨

パッケージマネージャー	コマンド
Homebrew	`brew install asdf`
Pacman	`git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` またはお好みの AUR ヘルパー

コンパイル済みバイナリをダウンロード - かんたん

依存関係のインストール

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

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

備考

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

asdfのインストール

https://github.com/asdf-vm/asdf/releases から、お使いのオペレーティングシステム/アーキテクチャの組み合わせに適したアーカイブをダウンロード。
アーカイブ内のasdfバイナリを$PATHのディレクトリに解凍。
type -a asdfを実行して、シェルの$PATHにasdfがあることを確認します。asdfのバイナリを置いたディレクトリがtypeの出力の1行目に表示されるはずです。うまくいかない場合は、2の手順が正しく行えていない可能性があります。

go install を使用

依存関係のインストール

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

備考

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

asdfのインストール

Goをインストールする
コマンドを実行: go install github.com/asdf-vm/asdf/cmd/asdf@v0.16.0

ソースコードからビルドする

依存関係のインストール

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

備考

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

asdfのインストール

asdfリポジトリをクローン:

shell

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

makeを実行。
asdfバイナリを$PATH上のディレクトリに解凍。
type -a asdfを実行して、シェルの$PATHにasdfがあることを確認します。asdfのバイナリを置いたディレクトリがtypeの出力の1行目に表示されるはずです。うまくいかない場合は、3の手順が正しく行えていない可能性があります。

2. asdfの設定

備考

ほとんどのユーザーは、asdfが管理するデータ(plugin, install, shim data)の保存先を変更する必要はありません。ただし、デフォルトの$HOME/.asdf以外を指定したい場合は変更することができます。別のディレクトリを指定するには、シェルのRCファイルでASDF_DATA_DIR変数をエクスポートしてください。

シェル、OS、インストール方法には様々な組み合わせがあり、その全てがここでの設定に影響します。あなたのシステムに最も適したものを選んでください。

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

Bash

macOS Catalina以降: デフォルトのシェルがZSHに変更されました。Bashに変更していない限り、ZSHの手順を参照してください。

Pacman: コマンド補完が必要な場合は、bash-completionをインストールしてください。

shimsディレクトリをパスに追加する(必須)

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

shell

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

カスタムデータディレクトリの設定(オプション)

~/.bash_profileに以下を追記します(先述したパス追加よりも上の行に書くこと):

shell

export ASDF_DATA_DIR="/your/custom/data/dir"

シェルのコマンド補完設定(オプション)

.bashrcに以下を追記します:

shell

. <(asdf completion bash)

Fish

shimsディレクトリをパスに追加する(必須)

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

shell

# ASDF configuration code
if test -z $ASDF_DATA_DIR
    set _asdf_shims "$HOME/.asdf/shims"
else
    set _asdf_shims "$ASDF_DATA_DIR/shims"
end

# Do not use fish_add_path (added in Fish 3.2) because it
# potentially changes the order of items in PATH
if not contains $_asdf_shims $PATH
    set -gx --prepend PATH $_asdf_shims
end
set --erase _asdf_shims

カスタムデータディレクトリの設定(オプション)

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

~/.config/fish/config.fishに以下を追記します(先述したパス追加よりも上の行に書くこと):

shell

set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir"

シェルのコマンド補完設定(オプション)

コマンド補完は以下を実行して手動で設定する必要があります:

shell

$ asdf completion fish > ~/.config/fish/completions/asdf.fish

Elvish

shimsディレクトリをパスに追加する(必須)

~/.config/elvish/rc.elvに以下を追記します:

shell

var asdf_data_dir = ~'/.asdf'
if (and (has-env ASDF_DATA_DIR) (!=s $E:ASDF_DATA_DIR '')) {
  set asdf_data_dir = $E:ASDF_DATA_DIR
}

if (not (has-value $paths $asdf_data_dir'/shims')) {
  set paths = [$path $@paths]
}

カスタムデータディレクトリの設定(オプション)

カスタムデータディレクトリを設定するには、上記のスニペットの以下の行を変更してください:

diff

-var asdf_data_dir = ~'/.asdf'
+var asdf_data_dir = '/your/custom/data/dir'

シェルのコマンド補完設定(オプション)

shell

$ asdf completion elvish >> ~/.config/elvish/rc.elv
$ echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

ZSH

Pacman: コマンド補完はZSHから使いやすい場所に配置されますが、自動補完を使うにはZSHの設定で有効化する必要があります。

shimsディレクトリをパスに追加する(必須)

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

shell

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

カスタムデータディレクトリの設定(オプション)

~/.zshrcに以下を追記します(先述したパス追加よりも上の行に書くこと):

shell

export ASDF_DATA_DIR="/your/custom/data/dir"

シェルのコマンド補完設定(オプション)

コマンド補完はZSHフレームワークのasdfプラグイン（asdf for oh-my-zshのようなもの）を使用するか、以下の手順で設定します:

shell

$ mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"
$ asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"

その場合は.zshrcに以下を追記します:

shell

# append completions to fpath
fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit

備考

ZSHフレームワークでカスタムされたcompinitセットアップを使っている場合は、compinitがフレームワークのソース配下にあることを確認してください。

コマンド補完はZSHフレームワークのasdfで設定するか、Homebrewの指示に従って設定する必要があります。ZSHフレームワークを使っている場合、asdf用のプラグインを更新してfpath経由で新しいZSH補完機能を正しく使えるようにする必要があるかもしれません。なお、Oh-My-ZSH asdfプラグインはまだ対応していません。ohmyzsh/ohmyzsh#8837 を参照してください。

PowerShell Core

shimsディレクトリをパスに追加する(必須)

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

shell

# Determine the location of the shims directory
if ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq '') {
  $_asdf_shims = "${env:HOME}/.asdf/shims"
}
else {
  $_asdf_shims = "$ASDF_DATA_DIR/shims"
}

# Then add it to path
$env:PATH = "${_asdf_shims}:${env:PATH}"

カスタムデータディレクトリの設定(オプション)

~/.config/powershell/profile.ps1に以下を追記します(先述したスニペットよりも上の行に書くこと):

shell

$env:ASDF_DATA_DIR = "/your/custom/data/dir"

PowerShellはコマンド補完に対応していません。

Nushell

shimsディレクトリをパスに追加する(必須)

~/.config/nushell/config.nuに以下を追記します:

shell

let shims_dir = (
  if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) {
    $env.HOME | path join '.asdf'
  } else {
    $env.ASDF_DATA_DIR
  } | path join 'shims'
)
$env.PATH = ( $env.PATH | split row (char esep) | where { |p| $p != $shims_dir } | prepend $shims_dir )

カスタムデータディレクトリの設定(オプション)

~/.config/nushell/config.nuに以下を追記します(先述したパス追加よりも上の行に書くこと)：

shell

$env.ASDF_DATA_DIR = "/your/custom/data/dir"

シェルのコマンド補完設定(オプション)

shell

# If you've not customized the asdf data directory:
$ mkdir $"($env.HOME)/.asdf/completions"
$ asdf completion nushell | save $"($env.HOME)/.asdf/completions/nushell.nu"

# If you have customized the data directory by setting ASDF_DATA_DIR:
$ mkdir $"($env.ASDF_DATA_DIR)/completions"
$ asdf completion nushell | save $"($env.ASDF_DATA_DIR)/completions/nushell.nu"

次に、~/.config/nushell/config.nuに以下を追記します:

shell

let asdf_data_dir = (
  if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) {
    $env.HOME | path join '.asdf'
  } else {
    $env.ASDF_DATA_DIR
  }
)
. "$asdf_data_dir/completions/nushell.nu"

POSIX Shell

shimsディレクトリをパスに追加する(必須)

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

shell

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

カスタムデータディレクトリの設定(オプション)

~/.profileに以下を追記します(先述したパス追加よりも上の行に書くこと):

shell

export ASDF_DATA_DIR="/your/custom/data/dir"

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`

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

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

shell

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

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

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

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

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

shell

asdf install nodejs latest

備考

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

6. バージョンをセット

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

警告

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

asdfはまずカレントディレクトリにある .tool-versions ファイルを探し、見つからなければ親ディレクトリを参照し .tool-versions ファイルが見つかるまでファイルツリーの上位階層を探索します。.tool-versionsファイルが見つからない場合、バージョン解決処理は失敗し、エラーが表示されます。

すべてのディレクトリに適用されるデフォルトのバージョンを設定したい場合、$HOME/.tool-versionsにバージョンを設定できます。特定のディレクトリで別のバージョンを設定しない限り、ホームディレクトリ以下のすべてのディレクトリに同じバージョンが設定されるようになります。

shell

asdf set -u nodejs 16.5.0

$HOME/.tool-versionsは次のようになります:

nodejs 16.5.0

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

asdfが最初にバージョンを探す場所は、現在の作業ディレクトリ（$PWD/.tool-versions）です。これはプロジェクトのソースコードやGitリポジトリを含むディレクトリです。目的のディレクトリでasdf setを実行すると、バージョンを設定することができます:

shell

asdf set nodejs 16.5.0

$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つのカテゴリに分けられます:

はじめよう ​

1. asdfのインストール ​

依存関係のインストール ​

asdfのインストール ​

依存関係のインストール ​

asdfのインストール ​

依存関係のインストール ​

asdfのインストール ​

2. asdfの設定 ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

シェルのコマンド補完設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

シェルのコマンド補完設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

シェルのコマンド補完設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

シェルのコマンド補完設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

シェルのコマンド補完設定(オプション) ​

shimsディレクトリをパスに追加する(必須) ​

カスタムデータディレクトリの設定(オプション) ​

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

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

プラグインの依存関係 ​

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

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

6. バージョンをセット ​

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

入門完了！ ​

はじめよう

1. asdfのインストール

依存関係のインストール

asdfのインストール

依存関係のインストール

asdfのインストール

依存関係のインストール

asdfのインストール

2. asdfの設定

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

シェルのコマンド補完設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

シェルのコマンド補完設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

シェルのコマンド補完設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

シェルのコマンド補完設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

シェルのコマンド補完設定(オプション)

shimsディレクトリをパスに追加する(必須)

カスタムデータディレクトリの設定(オプション)

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

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

プラグインの依存関係

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

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

6. バージョンをセット

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

入門完了！