バージョン管理を柔軟に! プロジェクト単位で「asdf」を使いこなす

開発ツール

技術解説

連載 [第12回] :

Windowsユーザーのための WSL2で始める Linux環境構築術

2025年5月7日(水)

田中智明

第12回目の今回は、プロジェクトごとにツールのバージョンを管理できるバージョンマネージャー「asdf」の導入と活用方法について解説します。

はじめに

近年、様々なツールやプログラミング言語を駆使してサービス開発を行うことが増えてきています。例えば、実行環境の構築にはIaCを使いますし、フロントエンドとバックエンドの開発にはそれぞれ別のプログラミング言語を使うことでしょう。これはある言語やツールの特性を理解し、使い分けることで効率化を図るのが目的です。使用するツールや言語が増えてくると、今まで動いていたはずのコードがある時点から動かなくなってしまったり、誰かの環境でしか再現しない問題などが発生することも多々あります。これには色々な原因が考えられますが、1つにバージョンの差異が挙げられます。

いくつかのプロジェクトを掛け持ちで開発に参加することもあるでしょう。あるプロジェクトでは古いバージョンに依存している一方で、別のプロジェクトでは最新のバージョンを使いたいといったケースも珍しくありません。このような状況ではツールやプログラミング言語をシステムにインストールしてしまうと、バージョンが固定され、並行して開発が行えなくなるため不都合が出てきます。

そこで便利なのが、プロジェクトごとに適切なツールのバージョンを管理できる「バージョンマネージャー」です。バージョンマネージャーにも複数の実装が存在しますが、有名なのが「asdf」でしょう。asdfはLinuxとmacOS向けにしかリリースされていませんが、こうしたLinux向けのツールでもWSLを使えば手軽にWindows上に導入できます。この記事では、WSL上でasdfを使う方法を紹介します。

バージョンマネージャーとは

バージョンマネージャーとは、プログラミング言語やツールの複数のバージョンをシステム内で共存させ、必要に応じて切り替えられるツールです。バージョンマネージャーを使用することで、開発者はシステム全体の設定を変更することなく、プロジェクト毎に最適なバージョンを選択できます。複数のプロジェクトで開発に参加している場合には必須のツールと言えるでしょう。

バージョンマネージャーには様々な実装が存在します。例えば、Pythonのバージョン管理ツールとしては「pyenv」が有名です。他にもGoは「goenv」、Node.jsは「nodenv」など、「~env」という名前で開発されていることが多くあります。もちろん、このルールから外れているツールもいくつか存在しますが、どれも「ソフトウェアとバージョンを管理できる」という点では同じです。

これらのバージョンマネージャーはプログラミング言語やツール毎に実装され、使い方も異なります。つまり、使用するツールやプログラミング言語が増えていくと、それに応じてバージョンマネージャーの種類も増え、それぞれの使い方を覚えていく必要がでてくるわけです。これでは効率化を図るために使い始めたツールが、効率化の足枷となってしまうと言っても過言ではありません。そこで筆者は、様々なツールや言語を1つのツールで管理できるasdfの使用を推奨しています。

asdfとは

asdfはプログラミング言語やツールのバージョンを統合的に管理できるバージョンマネージャーです。従来のバージョンマネージャーはツールや言語毎に実装されているため、使い方もバラバラでした。しかし、asdfは1つのツールで複数の言語、ツールのバージョンを管理できるため、プロジェクトに1つ用意しておくことでほとんどのバージョンを管理できます。

asdfで管理するバージョンはテキストベースの設定ファイル「.tool-versions」で定義されます。このファイルをプロジェクトのリポジトリにコミットしておくことで、チーム全員が同じバージョンのツール、言語を使用します。これにより、バージョンの差異によるトラブルを避けられるでしょう。

asdfを使ってみよう

asdfは日本語の公式ドキュメントが充実しています。今後の操作で迷った場合は、こちらのインストール手順を参考にしてください。

また、繰り返しになりますが、asdfはLinux向けのツールです。ここからの手順はWSL環境で実行してください。

asdfをインストールしよう

こちらから、下記のコマンドで自分のOSとアーキテクチャに合ったバイナリーをダウンロードしてください。バージョンは最新のものを使うと良いでしょう。

なお、私の検証マシンはWindows 11なので、ここでは執筆時点の最新バージョンである「asdf-v0.16.7-linux-amd64.tar.gz」をWSL上でダウンロードしています。
```
$ curl -LO https://github.com/asdf-vm/asdf/releases/download/v0.16.7/asdf-v0.16.7-linux-amd64.tar.gz
```
ダウンロードしたファイルを解凍し、asdfをパスの通ったディレクトリにインストールします。sudoコマンドの実行時にパスワードを求められた場合は、ユーザーのパスワードを入力してください。
```
$ tar xf asdf-v0.16.7-linux-amd64.tar.gz
$ sudo install -m 0755 asdf /usr/local/bin/asdf
$ rm asdf
```
asdfが実行できるか確認してみましょう。
```
$ asdf --version
asdf version v0.16.7
```
ダウンロードしたバージョンが表示されていればインストール完了です。もし、バージョンが表示されず「Command 'asdf' not found」と出た場合は、/usr/local/binにパスが通っていません。下記のコマンドを実行して、再度バージョンを表示させてみてください。
```
$ echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
$ exec $SHELL -l
```

コマンドの補完を有効にします。

$ echo '. <(asdf completion bash)' >> ~/.bashrc
$ exec $SHELL -l

「asdf」と入力後に[TAB]キーを押下すると、asdfのサブコマンドなどが補完できるようになります。asdfでインストールしたツールは「$HOME/.asdf/shims」に展開されます。しかし、このディレクトリにはパスが通っていないはずなので、PATHに追加する必要があります。下記のコマンドを実行しましょう。
```
$ echo 'export PATH="$HOME/.asdf/shims:$PATH"' >> ~/.bashrc
$ exec $SHELL -l
```

これでインストールは完了です。

依存パッケージをインストールしよう

asdfはGitに依存します。下記のコマンドを実行し、Gitをインストールしてください。

$ sudo apt install -y -U git

必須ではありませんが、build-essentialも入れておくと良いかもしれません。というのも、asdfはインストール時にツールの依存ライブラリやツール自体のビルドを行うことがあるためです。必要に応じてインストールしてください。

$ sudo apt install -y -U build-essential

asdfでバージョンを管理するための手順を理解しよう

asdfでプログラミング言語やツールのバージョン管理を行うには、まずプラグインを追加します。言語やツールのプラグインを追加すると、使用可能なバージョン一覧の取得やインストール、バージョンのスイッチなどが行えるようになります。

asdfを使用するにあたり、全体の流れとしては下記の手順になります。

プラグインの検索
プラグインの追加
利用可能なバージョンを調べる
特定のバージョンを指定してインストール
インストールしたバージョンを有効化

「1. プラグインの検索」や「3. 利用可能なバージョンを調べる」は必ずしも必要な手順ではありませんが、プラグインや使用可能なバージョンを調べることはよくある手順なので、この機会に覚えておきましょう。

特定のバージョンをインストールしてみよう

ここまでの解説でasdfのインストールと初期セットアップが完了したので、続いてツールをインストールしましょう。今回は例としてNode.jsの最新バージョンをインストールしてみます。

まずは、asdfにNode.jsのプラグインがあるか確認してみましょう。

$ asdf plugin list all | grep nodejs
nodejs        https://github.com/asdf-vm/asdf-nodejs.git

1件ヒットしました。このプラグインを追加します。
```
$ asdf plugin add nodejs
```
プラグインが追加できたか見てみましょう。
```
$ asdf list
nodejs
    No versions installed
```
プラグインは追加しましたが、まだNode.js自体はインストールしていないため「No versions installed」と表示されます。Node.jsで利用可能なバージョンを確認してみましょう。
```
$ asdf list all nodejs
...
23.9.0
23.10.0
23.11.0
```
この中から使用したいバージョンを選択します。最新のバージョンが知りたい場合は下記のコマンドを実行します。
```
$ asdf latest nodejs
23.11.0
```
執筆時点では「23.11.0」が最新のようなので、このバージョンをインストールします。
```
$ asdf install nodejs 23.11.0
```
例のコマンドでは「23.11.0」を直接指定しましたが、とにかく最新で良いという場合は「latest」を指定することで、最新のバージョンをインストールできます。

このlatestタグは実は結構優秀で、「latest:version」とすると「version」で指定したバージョンの最新がインストールできます。と言ってもちょっと分かりづらいですよね。具体的には「latest:23」とすると、Node.jsのメジャーバージョンが23で、マイナーバージョン、パッチバージョンは最新がインストールされます。「latest:22」とすれば22の最新がインストールされるというわけです。
指定のバージョンが正しくインストールされたか確認してみましょう。
```
$ asdf list nodejs
  23.11.0
```
インストールしたバージョンが表示されれば成功です。

ここで余談ですが、プログラミング言語やツールのバージョンは「XX.YY.ZZ」の3つで表されることがあります。これは「セマンティックバージョニング」と呼ばれ、XXをメジャーバージョン、YYをマイナーバージョン、ZZをパッチバージョンと呼びます。メジャーバージョンは互換性のない変更が加えられたときにカウントアップされます。マイナーバージョンは後方互換性が保たれた機能追加、パッチバージョンは後方互換に伴うバグ修正などでカウントアップされます。XXの部分が同じであれば、YY.ZZ部分が変わっても互換性が維持されているはずなので、なるべくならば最新版を使いたいことが多いでしょう。そのような理由から「latest:version」を指定します。セマンティックバージョニングに興味が沸いたらセマンティックバージョニング 2.0.0のドキュメントを見てみると良いでしょう。

プロジェクト毎にバージョンを使い分けよう

ここまでの説明で、ツールのインストール方法は理解できたかと思います。続いて、プロジェクト毎にツールのバージョンを使い分けてみます。これがasdfの本命の機能と言えます。

今回は架空のプロジェクト「project_a」と「project_b」ディレクトリを用意して動作を説明します。

まずはディレクトリを作成しましょう。
```
$ mkdir ~/project_{a,b}
```
project_aディレクトリに移動し、バージョンをセットします。
```
$ cd ~/project_a
$ asdf set nodejs 23.11.0
```
このコマンドを実行すると、カレントディレクトリに「.tool-versions」という名前のファイルが作成されます。このファイルには使用するツールとそのバージョンが記述されています。そのため、ファイルを共有することで他の環境でもこのディレクトリ下では同じバージョンのツールが使用できます。
```
$ node --version
v23.11.0
```

続いて、project_bに移動して別のバージョンをインストールしてみましょう。

$ cd ~/project_b
$ asdf install nodejs latest:22
$ asdf set nodejs latest:22
$ node --version
v22.14.0

バージョン22の最新が表示されれば成功です。現在どのバージョンを使用しているのか、見てみましょう。
```
$ asdf list nodejs
 *22.14.0
  23.11.0
```
現在使用中のバージョンには、先頭に「*」が付いています。project_aディレクトリにも移動して確認してみてください。

チームメンバーがセットアップしたバージョンを使ってみよう

ここまでは自分で特定のバージョンをインストールし、使用できるようセットアップしました。自分がプロジェクト内でバージョンを決定する権限を持っているのなら良いのですが、テックリードなどがバージョンをコントロールしている場合もあるでしょう。ここでは、他の人がセットアップした「.tool-versions」を使って、自分の環境をセットアップしてみます。

project_cディレクトリを作成し、.tool-versionsを用意します。
```
$ mkdir ~/project_c
$ cd ~/project_c
$ echo 'golang 1.24.2' > .tool-versions
```
.tool-versionsの中身を確認するとGoを使用することが分かります。golangプラグインを追加しましょう。
```
$ asdf plugin add golang
```
.tool-versionsファイルと同じ階層に移動し、指定のバージョンをインストールします。
```
$ asdf install
```
installコマンドでツール名もバージョンも指定していませんが、.tool-versionsがあった場合は、そこに記載されたバージョンが自動でインストールされます。ただし、プラグインの追加だけは自分で行う必要があることに注意してください。
```
$ go version
go version go1.24.2 linux/amd64
```
Goのバージョンが取得できればインストールが正常に終了しています。

その他の選択肢

asdfは非常に人気のあるバージョンマネージャーですが、いくつか欠点もあります。ここではそうした欠点を改善した、別のバージョンマネージャーを紹介します。ツール選定の参考にしてください。

mise

asdfは様々なプラグインでバージョンを管理できるため一見便利そうですが、プラグインの管理方法に懸念があります。asdfにはプラグインを管理する2つの仕組みが存在します。1つはasdf-communityというGitHubオーガナイゼーションにリポジトリを作成する方法、もう1つはasdf-pluginsリポジトリにPRを作成してマージしてもらう方法です。

asdf-communityはasdfのコミュニティでプラグインをメンテナンスするため比較的安全と言えます。asdfもこちらの方法を推奨しています。

・asdf-community
> If you're creating a new plugin consider creating it as part of the asdf-community project. This is a separate community project with consolidated maintenance.

asdf-pluginsは一定のルールに則ってPRを出せば、明らかな問題がない限りは誰でもプラグインを追加できます。そして、そのプラグインのセキュリティはプラグインの作成者に委ねられます。また、使用者側も自己責任で使用するように書かれています。

・Security
> Plugins are the responsibility of their creators and not covered by the asdf policy. It is the responsibility of the user to evaluate each plugin they use for security concerns, even those in the asdf-community repositories.

この問題を解決し得るツールとして「mise(旧rtx)」というものがあります。miseは独自のプラグインリポジトリを設けており、オーナーだけがプラグインのコミットを許可されています。そのため、悪意のあるコードや1度しか使用しないであろうプラグインが追加されることを阻止できます。

・Problems with asdf-vm/asdf-plugins
・Plugin Development in mise-plugins

miseはasdfの.tool-versionsファイルを読み込めるためasdfと互換があります。基本的な使い方もasdfと同様です。つまり、ツールを移行する場合は、今まで使用していたasdfをmiseに変更する以外に移行の手間がかかりません。

aqua

「aqua」は日本人によって開発されているバージョンマネージャーです。aquaの開発者は「tfaction」と呼ばれるGitHub Actionsの開発者でもあります。開発者による日本語のドキュメントが充実しているため、導入も簡単でしょう。

なお、aquaはasdfと互換がないため、aquaを使用するならaqua用のセットアップが必要になります。

おわりに

1つのプロジェクトで複数の言語、ツールを使って開発することが一般的となった今、さらに複数のプロジェクトを並行して開発することも少なくありません。このような環境下で自分なりのバージョン管理を行なっていては、それだけで手いっぱいになってしまいます。また、複数の人が関わってくるチーム開発では、全員のツール、バージョンを合わせることも重要となります。そうなればバージョンマネージャーの存在は必須でしょう。

この機会にバージョンマネージャーを導入し、プロジェクトのツール、バージョンを管理してみてはいかがでしょうか。