メインコンテンツへスキップ
Toolsbase.

asdf → mise 移行ガイド — .tool-versionsはそのまま【コマンド対応表つき】

Toolsbase編集部
miseasdfバージョン管理開発環境ターミナル

Node.js・Python・Ruby などのバージョン管理ツールとして長く定番だった asdf から、後発の mise（mise-en-place）への移行が進んでいます。mise は asdf の .tool-versions をそのまま読める互換性を持ちながら、環境変数管理（direnv 相当）とタスクランナーまで1つに統合したツールです。

この記事では、asdf から mise への移行を「インストール → シェル統合の切り替え → ツールの一括インストール → asdf の撤去」の順で解説します。コマンド対応表は、当サイトの asdfコマンド一覧（23コマンド）と miseコマンド一覧（60コマンド）の検証済みデータを突き合わせて作成しています。

個々のコマンドの詳しい説明・オプション・使用例が必要なときは、上記のリファレンス2ページを併用してください。本記事は Go 版 asdf（v0.16 以降）/ mise v2026.x（2026年7月時点）の情報に基づいています。

1. なぜ asdf から mise へ移行するのか

きっかけとして大きいのは、asdf 自体の世代交代です。asdf は2025年初頭の v0.16 で Bash 実装から Go 実装へ全面リライトされ、大幅に高速化した一方、asdf global / asdf local が asdf set に統合されるなどコマンド体系が変わりました。「どうせコマンドを覚え直すなら」と、このタイミングで mise を検討するユーザーが増えています。

mise 側の魅力は次の3点に集約されます。

  • asdf 資産との互換性: .tool-versions をそのまま読み込み、asdf のプラグインも利用できる。移行に書き換え作業がほぼ発生しない
  • shim を介さない高速動作: asdf の代名詞だった reshim 作業が原則不要になり、which node が実バイナリを直接指す
  • 1ツール3役: バージョン管理に加えて、環境変数管理（direnv 代替）とタスクランナーを mise.toml 1ファイルに統合できる

2. mise とは — asdfユーザー視点の4ポイント

mise は Rust 製の開発ツールマネージャーです。asdf ユーザーの視点で押さえておきたい特徴は次の4つです。

  • .tool-versions 互換: 既存のリポジトリに置かれた .tool-versions を無変換で認識する。チームの他メンバーが asdf のままでも共存できる
  • コアツールはプラグイン不要: Node.js・Python・Ruby・Go など主要ツールはレジストリ（900超のツール）に内蔵されており、mise use node@22 だけで完了。asdf のような「まずプラグインを追加」という手順自体が不要になる
  • デフォルトは shim レス: PATH を直接操作する方式のため reshim が不要。IDE 連携などで shim が必要な場合は mise activate zsh --shims で従来方式も選べる
  • ニッチなツールは asdf プラグインで補完: レジストリにないツールも mise plugins install custom https://github.com/user/asdf-custom.git のように asdf プラグインの Git URL を指定して利用できる

3. 移行手順（4ステップ）

Step 1: mise のインストール

# macOS / Linux（Homebrew）
brew install mise

# インストーラースクリプト
curl https://mise.run | sh

Step 2: シェル統合の切り替え

.zshrc（または .bashrc）から asdf の初期化行を削除し、mise の1行を追加します。

# 削除: asdf の初期化行（例）
# export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

# 追加: mise のシェル統合
eval "$(mise activate zsh)"

asdf と mise を同時に有効化しないでください。 両方が PATH や shim を操作すると、どちらのバージョンが使われるか不定になります。切り替えたらシェルを開き直します。

Step 3: ツールの一括インストール

プロジェクトディレクトリ（または .tool-versions のある場所）で次を実行します。

mise install

mise install は .tool-versions と mise.toml に定義された全ツールをインストールします。asdf でインストール済みのバージョンも、mise 側のディレクトリ（~/.local/share/mise/）に別途インストールし直す動きになります（asdf のインストール物を流用するわけではありません）。

nvm・pyenv・rbenv から合流する場合は、専用の同期コマンドで既存インストールを取り込めます。

mise sync node --nvm   # nvm のNode.jsバージョンをmiseから利用可能に
mise sync python       # pyenv のPythonバージョンを同期
mise sync ruby         # rbenv のRubyバージョンを同期

Step 4: 動作確認と asdf の撤去

mise doctor          # 環境の問題を診断
mise ls --current    # 現在有効なツールとバージョンを確認
node --version       # 実際にツールが動くか確認

問題がなければ asdf を削除します（Homebrew の場合 brew uninstall asdf、データは ~/.asdf を削除）。削除は必ず mise での動作確認が済んでからにしてください。

4. コマンド対応表（asdf → mise）

対応表は両リファレンスの掲載コマンドに基づきます。

ツール管理

やりたいこと asdf mise 備考
バージョンを設定 asdf set <tool> <ver> mise use <tool>@<ver> miseはインストールも同時に実行し mise.toml に記録。グローバル設定は mise use --global
インストールのみ asdf install <tool> <ver> mise install <tool>@<ver> 設定ファイルは変更しない
定義済みツールの一括インストール asdf install mise install どちらも引数なしで一括
アンインストール asdf uninstall mise uninstall
現在のバージョン確認 asdf current mise ls --current（-c）
インストール済み一覧 asdf list mise ls
利用可能な全バージョン asdf list all <tool> mise ls-remote <tool>
最新の安定版を確認 asdf latest mise latest 同名

プラグイン管理

やりたいこと asdf mise 備考
プラグイン追加 asdf plugin add mise plugins install miseはコアツールでは不要（レジストリ内蔵）。asdfプラグインのGit URL指定も可
インストール済み一覧 asdf plugin list mise plugins ls
利用可能な全プラグイン asdf plugin list all mise plugins ls-remote / mise registry mise search でレジストリ検索も可
プラグイン削除 asdf plugin remove mise plugins uninstall
プラグイン更新 asdf plugin update / --all mise plugins update

ユーティリティ

やりたいこと asdf mise 備考
インストールパス表示 asdf where mise where 同名
実行ファイルのパス表示 asdf which mise which miseはshimレスのため実バイナリを直接指す
指定バージョンでコマンド実行 asdf exec mise exec
shim 再生成 asdf reshim mise reshim miseは通常運用では不要（--shims 統合時のみ）
バージョン表示 asdf version mise version
シェル補完 asdf completion mise completion
環境診断 asdf info（情報表示） mise doctor miseは問題の診断まで行う

asdf に対応がない mise の機能

移行後に新しく使えるようになる代表的なコマンドです。

コマンド 内容
mise upgrade / mise outdated ツールの一括アップグレードと更新可能一覧
mise prune 使われていないバージョンの掃除
mise run / mise tasks ls mise.toml に定義したタスクの実行・一覧（タスクランナー）
mise set / mise env 環境変数の設定・エクスポート（direnv 代替）
mise sync node / python / ruby nvm・pyenv・rbenv からの取り込み
mise self-update mise 自身の更新

5. .tool-versions と mise.toml

移行直後は .tool-versions のままで問題ありません。mise が無変換で読み込むため、チームリポジトリのファイルを書き換えずに自分だけ mise へ移行できます。

mise をフル活用するなら、環境変数・タスクまで一元化できる mise.toml への移行を検討します。

[tools]
node = "22"
python = "3.12"

[env]
DATABASE_URL = "postgres://localhost/mydb"

[tasks.test]
run = "npm test"

mise use node@22 を実行すると mise.toml に自動で追記されるため、手書きする必要はほとんどありません。環境変数は mise set DATABASE_URL=postgres://localhost/mydb、タスクは mise tasks add からも登録できます。

6. つまずきやすいポイント

  1. asdf と mise の二重 activate: 最も多い事故です。.zshrc に両方の初期化行が残っていると PATH の解決が不定になります。移行時に必ず asdf の行を削除してください
  2. shim 前提の環境: JetBrains 系 IDE や一部の CI 設定が「shim のパス」を直接参照している場合、shim レスの mise では見つからなくなります。mise activate zsh --shims で shim 方式に切り替えるか、mise which <tool> で実パスを設定し直します
  3. asdf env と mise env は別物: asdf の env は「shim 実行環境でユーティリティを実行」するコマンドですが、mise の env は「環境変数をシェル形式でエクスポート」します。同名でも役割が違うので読み替えが必要です
  4. インストール物は引き継がれない: mise はツールを ~/.local/share/mise/ に自前でインストールします。mise install の初回はダウンロードが走るため、ネットワーク環境の良いところで実行してください（nvm/pyenv/rbenv からは mise sync で既存物を流用できます）
  5. 旧 Bash 版 asdf（v0.15 以前）からの移行: asdf global / asdf local は Go 版で既に asdf set へ統合されています。mise では mise use --global / mise use がそれぞれの後継です

よくある質問

.tool-versions はそのまま使えますか？

はい。mise は .tool-versions を無変換で読み込みます。チームの他メンバーが asdf を使い続けていても、同じリポジトリで共存できます。mise.toml への移行は任意です。

asdf のプラグインはそのまま使えますか？

コアツール（Node.js・Python・Ruby・Go など）はレジストリに内蔵されているためプラグイン自体が不要です。レジストリにないニッチなツールは、mise plugins install <名前> <GitリポジトリURL> で asdf プラグインを指定して利用できます。

asdf と mise を併用できますか？

シェル統合（activate）の併用は非推奨です。PATH の解決順によってどちらのツールが使われるか不定になります。移行期間中も、シェル統合は mise だけにして、必要なら asdf exec で旧環境を明示的に呼び出す運用が安全です。

reshim はもう不要ですか？

デフォルトのシェル統合（PATH 直接操作）では不要です。--shims オプションで shim 方式を選んだ場合のみ、asdf 同様に mise reshim の出番があります。

direnv は不要になりますか？

mise.toml の [env] セクション（または mise set）でディレクトリ単位の環境変数を管理できるため、多くのケースで direnv を置き換えられます。

移行後、asdf はいつ削除してよいですか？

mise doctor と mise ls --current で環境を確認し、主要ツールが実際に動くことを検証してからにしてください。~/.asdf を削除すると asdf 側のインストール物はすべて消えます。

まとめ

  • mise は .tool-versions 互換のため、移行の実作業は「シェル統合の切り替え + mise install」の2つが本体
  • コマンドは install / where / which / latest など多くが同名で移行できる。大きな違いは asdf set → mise use（インストール同時実行）と、プラグイン追加が原則不要になる点
  • shim レス動作で reshim から解放される一方、shim 前提の IDE/CI 設定は --shims で救済する
  • 移行後は環境変数管理（direnv 代替）とタスクランナーが mise.toml 1ファイルで使えるようになる

コマンドの全一覧・詳しい説明・使用例は、検証済みデータでメンテナンスしている以下のリファレンスを参照してください。