mise

mise

mise は、このスキルが適用されるプロジェクトで許可されている唯一のランタイムおよびツールマネージャーです。 各プロジェクトでは、リポジトリのルートにある mise.toml ですべてのツールを固定し、 解決済みのバージョンをコミット済みの mise.lock に、 依存関係グラフをコミット済みの .mise/locks/ に記録し、 ubi および asdf バックエンドを無効にして、 Python CLI は pypi: を、 Node CLI は npm を経由させ、 それ以外には aqua（または mise 組み込みの core）を使用します。

厳守事項

1. マネージャーは mise のみです。 brew install、 nvm、 asdf、 volta、 fnm、 pyenv、 rbenv、 tfenv、 goenv、 CLI 用の pip、pipx、uv tool、 アドホックなインストーラー、 curl パイプスクリプトは使用しません。

2. すべての mise.toml に、次の [settings] ブロックを含めます。

   [settings]
   disable_backends = ["ubi", "asdf"]
   lockfile = true
   

   disable_backends は、プロジェクト全体の解決チェーンから ubi と asdf を取り除きます。 mise は aqua と core のエントリーを維持するため、core ランタイム（go、node、python など）には影響しません。 lockfile = true にすると、mise が mise.lock を読み書きします。

3. ツールごとにバックエンドを指定します。

   • Python CLI（例：black、ruff、poetry）→ pypi: — 各 CLI はそれぞれ独自のロック済み依存関係グラフ、 独自の venv、 独自のプライベート Python を持つため、 aqua にバンドルされた Python が紛れ込むことはありません （下記の Python CLI：完全な分離 を参照）。 pipx: は同じバックエンドを指す別名で、非推奨ではないため、 既存のエントリーは同じルールのもとでそのまま使用できます。 新規エントリーには pypi: を使用してください。 mise は pipx:x と pypi:x を別々のツールとして扱います。 プレフィックスを変更すると、新たなインストールとロックエントリーが作成されます。
   • Node／JS CLI（例：typescript、prettier、eslint）→ npm: — mise の npm バックエンドは mise 管理下の Node を通じてインストールするため、 aqua にバンドルされた Node が紛れ込むことはありません。
   • それ以外 （ランタイム、terraform や kubectl などの単一バイナリ CLI）→ 名前のみを指定し、 mise が aqua または core に解決します。
   • aqua にない Rust CLI → cargo: aqua にない Ruby CLI → gem:
   • ubi と asdf は使用禁止です（ルール 2 を参照）。

4. バージョンは完全な形式で固定します。 latest、 lts、 メジャーバージョンのみ（20）、 マイナーバージョンのみ（20.11）は使用しません。 常に完全なバージョン（20.11.1、1.22.4、1.7.5）を指定します。 mise.lock と .mise/locks/ は mise.toml とともにコミットします。

5. プロジェクト設定ファイルは、リポジトリのルートにある mise.toml です。 .mise.toml、 .tool-versions、 .nvmrc、 .python-version、 .ruby-version は使用しません。 .mise.toml がすでに存在する場合は、 その場で編集せず、 移行手順を実行してください。

6. 対象範囲は [tools] と [settings] セクションのみです。 さらに、Python ガードブロックと [env] の venv エントリーも対象に含みます（下記を参照）。 その他の [env] エントリー、 [tasks]、 および他のセクションは、別途対応してください。

7. ローカルのセットアップのみです。 CI 統合はこのスキルの対象外です。

8. mise.lock と .mise/locks/ は mise が生成するものであり、手作業で編集してはいけません。 これらに書き込めるのは mise コマンドのみです。 通常は mise lock を使用します。 バージョン、 チェックサム、 プラットフォームエントリー、 依存関係グラフを含め、手作業または mise 以外のツールで作成、編集、パッチ適用をしてはいけません。 ロックファイルに記録される内容を変更する場合は、 mise.toml を編集して mise lock を実行してください。 ロックファイルはそれに従って更新されます。

Python CLI：完全な分離

Python パッケージは、1 つのインタープリターにのみインストールされ、 同じインタープリターで実行されます。 「ある Python にインストールし、別の Python で実行したため、パッケージが見つからない」 という状況は起こり得ません。 これには mise 2026.10.24 以降が必要です。 mise --version が古い場合は、 まずユーザーにアップグレードを依頼してください。

各 pypi: エントリーで Python を指定し、 その隣で uv を固定します。

[tools]
uv = "0.13.6"
"pypi:black" = { version = "24.4.2", python = "3.14.10" }

各ツールには、次のものが用意されます。

• 専用のインタープリター。 python オプションには完全なバージョンを指定します。 mise はそのランタイムをシェルの PATH に追加せずにインストールし、 [tools] 内の python の固定によってツールがそれ以外の環境で動くこともありません。 このオプションを指定しない場合、ツールはプロジェクトの python を使用し、 そのバージョンを更新するたびに一緒に移行します。 それ以外の場合は PATH 上で最初に見つかった Python を使用し、 その Python がパッケージの要件を満たさない場合は、 uv が自らダウンロードした CPython を使用します。
• 専用の venv。 installs/pypi-<tool>/<version>~uv~<hash>/ に作成され、 system と user の site-packages は無効になり、内部に pip はありません。 PATH に追加されるのはツールのコマンドのみで、 venv の python は追加されません。 同じ依存関係グラフをロックするリポジトリ間では、venv が共有されます。
• ロックされた依存関係グラフ。 mise lock は、すべての wheel のハッシュを含む pyproject.toml と uv.lock を .mise/locks/pypi-<tool>/<version>~<hash>/ に書き込み、 パスとダイジェストを mise.lock に記録します。 --locked インストールでは、uv sync --frozen --no-build によりロックを再現します。 wheel のみが使われるため、 インストール時にパッケージのコードが実行されることはありません。

これらのツールのロックとインストールには uv を使います。 依存関係グラフをロックできる最古のバージョンは 0.12.10 ですが、 目標にするバージョンではありません。 0.13.4 より前のリリースには既知の勧告があるため、 現行バージョンを固定してください。 [settings] の pipx.uvx = true は廃止されています。 インストール済みの uv があれば、すでにデフォルトのインストーラーとして使われるため、 見つけたら削除してください。 プロジェクト自体が Python を実行する場合に限り、[tools] で python を固定してください。 ツールがそれを必要とすることはありません。

ガードブロック

pypi: ツールまたは python の固定を含む mise.toml には、 ルール 6 の例外として、次のブロックも記述します。

[env]
PYTHONPATH = false               # would shadow a tool's own packages
PYTHONHOME = false               # would redirect or break the interpreter
PIP_REQUIRE_VIRTUALENV = "true"  # pip refuses to install outside a venv
UV_PYTHON_DOWNLOADS = "never"    # uv cannot fetch a CPython of its own

venv を使っても PYTHONPATH は遮断されません。 そこから見つかったパッケージは、ツールのインポートを乗っ取ります。 紛れ込んだ pip install は、その Python を使うすべてのプロジェクトで共有されるランタイムにインストールされます。 mise は、シェルをアクティベートした場合、 mise x を使った場合、 および shim 経由の場合にこのブロックを適用します。 ツールをインストール先のフルパスから起動した場合のみ、この制限を回避できます。

ツールの分離を保つ

• ツールはコマンド（black）で実行します。 ラッパーは使わず、python -m black として実行しないでください。 シェルの python にはそのパッケージがなく、あってはなりません。 そこで No module named black と表示されるのは分離が機能している証拠であり、 パッケージを再インストールして解決する問題ではありません。

• 手動でインストールしないでください。 CLI のために pip install、 uv pip install、 pipx install、 uv tool install を実行したり、 ツールの venv に何かをインストールしたりしないでください。 プラグインはツールの with オプションを使い、 独自のコマンドを持つ連携ツールは expose を使います。 どちらも == で固定し、ツールと一緒にロックします。

  "pypi:ansible-core" = { version = "2.21.5", python = "3.14.10", expose = ["ansible-lint==26.9.0"] }
  

• uvx_args や pipx_args は使わないでください。 これらはロックできません。 ツールのエントリーがバージョンのみになり、 --locked インストールで拒否されます。 代わりに python、with、expose を使ってください。

• プロジェクト自身のコードがインポートするライブラリは、ツールではありません。 pypi: を指定してもインポート可能にはなりません。 詳細は以下の「Python で書かれたプロジェクト」を参照してください。

ツールが実際に使用する Python を確認するには、次のようにします。

grep -E '^(home|version_info)' "$(mise where pypi:<tool>)/.mise-uv/.venv/pyvenv.cfg"

home は installs/python/<the pinned version>/bin である必要があります。 そのファイルが存在しない場合、ツールは依存関係グラフからインストールされていません。 shim が PATH にある場合、 別の Python にフォールスルーするときでも command -v python3 は shim を返します。 代わりに python3 -c 'import sys; print(sys.executable)' を実行してください。

Python で書かれたプロジェクト

python を固定し、mise でプロジェクトの venv をアクティブな状態に保ちます。

[tools]
python = "3.14.10"

[env]
_.python.venv = { path = ".venv", create = true }

mise activate を有効にしたターミナルでは、 python script.py を実行するとラッパーなしでその venv が使われ、 mise が初回使用時に venv を作成します。 プロジェクトに uv がない場合、 pip も venv のものになるため、 pip install したパッケージは python から参照できます。 プロジェクトに uv がある場合、venv に pip はありません。 パッケージを pyproject.toml で宣言し、uv sync を実行してください。 同じプロジェクトの pypi: ツールは、独自の Python と venv を使います。 .gitignore に .venv/ を追加してください。

shim だけでは venv がアクティブにならないため、 エージェントのように mise activate を使わないシェルでは、 python を実行すると No module named … が表示されます。 その場合は .venv/bin/python を呼び出してください。

プロジェクトとマシン

プロジェクト同士は互いに参照しません。 それぞれのプロジェクトで使えるのは、その mise.toml に記載されたツールだけです。 また、2 つのプロジェクトで、同じツールを異なるバージョンや Python に固定できます。

マシンのグローバル設定は意図的に継承されます。 そのツール（たとえば docker）はすべてのプロジェクトで引き続き使え、 プロジェクトの設定項目はグローバル設定を上書きします。 ただし、これは上記の分離を弱めるものではありません。 グローバルな Python CLI もほかと同様に独自の venv を使い、 グローバルな python で、独自のものを指定しているツールを移動することはできません。 グローバル設定が決めるのは、Python が固定されていないプロジェクトで python3 が何を指すかだけです。 そのため、グローバル設定には python 自体を含めないでください。 親ディレクトリの mise.toml も同じように継承されます。 単独で動作させる必要があるプロジェクトの上位には、mise.toml を置かないでください。

mise lock で依存関係グラフが作成されない場合

mise lock はグラフを書き込めなかった場合も終了コード 0 を返すため、 終了コードからは何も判断できません。 mise.lock のロック済みエントリーには uv の行があります。

[[tools."pypi:black"]]
version = "24.4.2"
backend = "pypi:black"
specifiers = ["24.4.2"]
uv = { path = ".mise/locks/pypi-black/24.4.2~87de8a48", digest = "sha256:…" }

version、backend、specifiers だけのエントリーには、依存関係グラフがありません。 原因は mise lock の出力から確認できます。

出力に含まれる内容	原因	解決方法
uv >= 0.12.10 is unavailable	uv がまだインストールされていない	lock and install の手順 1 を行ってから、再度ロックする
Python dependency locks require uv >= 0.12.10	固定されている uv が古すぎる	現行の uv を固定する
No interpreter found	python オプションがない、またはそのランタイムがインストールされていない	オプションを追加し、lock and install の手順 1 を行って再ロックする
has no usable wheels	依存関係に、その Python 用の wheel がない	Python のバージョンを下げる（下記参照）
uvx_args or pipx_args	これらのオプションはロックできない	python、with、expose に置き換える
exclude-newer	リリースが minimum_release_age（デフォルトは 24h）より新しい	待つか、古いバージョンを固定する
uses lockfile format version	古いロックファイル。形式 0 と 1 には依存関係グラフが含まれない	mise lock --upgrade

has no usable wheels の通常の原因は、新しい Python です。 依存関係グラフは wheel だけをインストールするため、 すべての依存関係がそのインタープリター用の wheel を公開している必要があります。 たとえば PyYAML 6.0.3 の wheel は cp314 までのため、 cookiecutter 2.7.1 では Python 3.15.2 ではなく Python 3.14.10 を使います。 ソースビルドを許可して解決しようとしてはいけません。 依存関係グラフ全体に対応する wheel がある最新の Python を選び （mise latest [email protected] はマイナーバージョン系列を解決します）、 理由をツールの横に記録してください。

# 3.14, not 3.15: PyYAML 6.0.3 ships no cp315 wheels.
"pypi:cookiecutter" = { version = "2.7.1", python = "3.14.10" }

mise が実行する内容の確認

mise registry <tool> を実行して、ツールに対する mise のバックエンドチェーンを確認します。 ubi と asdf が無効になっている場合、 mise はチェーン内の次のエントリーに進みます （通常は aqua または core です）。 残りがない場合、 mise はインストールを拒否します — これは想定どおりの明示的な失敗であり、 以下の ツールが利用できない場合 の手順を開始するきっかけになります。

実行前に確認する

以下のいずれかが不明な場合は、ユーザーに確認してください。

• 固定する正確なバージョン — 決して推測せず、 latest も指定しないでください。
• pypi も npm も該当せず、aqua にもツールがない場合に、どのバックエンドを使うか。
• プロジェクト独自のコードが PYTHONPATH に依存しているかどうか — ガードブロックでこれを解除します。
• 移行中に古い設定ファイル （.nvmrc、.tool-versions、Brewfile など）を削除するかどうか。
• asdf の例外を設けるかどうか — 以下の ツールが利用できない場合 を参照してください。

ネットワークに接続できず「最新」のバージョンを確認できない場合は、 推測せずに正確なバージョンをユーザーに尋ねてください。

ドキュメントに照らした記憶の確認

mise の設定、レジストリーのエントリー、バックエンドの動作はリリースごとに変わります。 ここに記載された内容（バックエンド構文、設定キー、レジストリーの内容、信頼の動作、ロックファイルの仕様など）に 見慣れない点や古くなっている点があれば、設定を書いたりコマンドを実行したりする前に https://mise.jdx.dev/ で確認してください。 推測しないでください。

手順：ロックとインストール

ほかの手順はここで終了します。 mise lock はパッケージコードを実行しないため、 何か問題があってもインストール前に判明します。

1. [tools] に pypi: ツールがある場合は、 ロックに必要なものをインストールします。 uv、および異なる python オプションごとに 1 つの python@<version> です。

   mise install uv [email protected]
   

   uv がないと、mise lock は依存グラフを記録しません。 ランタイムがないと、解決に使うインタープリターがありません。 ここでの WARN python installed but not activated は想定どおりです。 ランタイムはツール専用のまま維持されます。

2. ロックファイルと依存グラフを作成します。

   mise lock
   

   ロックファイルが古い形式だという警告が表示された場合は、 mise lock --upgrade を実行します。

3. mise.lock 内のすべての pypi: エントリーに uv の行があることを確認します。 ないものがあれば、 作業を止めて原因を修正してください（mise lock が依存グラフを作成しない場合 を参照）。

4. 厳密にインストールします。

   MISE_IGNORED_CONFIG_PATHS="$HOME/.config/mise" mise install --locked
   

   この変数により、このコマンドの実行中にマシンのグローバルツールが使われないようにします。 --locked を指定すると、それらについてもロックエントリーが必要になり、 is not in the lockfile で失敗します。 それらは通常どおりプロジェクト内で利用できます。 --locked は、依存グラフの欠落、サイドカーファイルの欠落、または依存グラフの編集があると失敗します。 通常の mise install は失敗しません。 利用可能な依存グラフがない場合は uv tool install にフォールバックし、 改めて依存関係を解決してソース配布物をビルドすることがあり、 そのコードが実行されます。 また、編集された依存グラフも受け入れてダイジェストを書き換えます。 mise x も通常の方法で不足しているツールをインストールするため、 ツールを起動する前にこの手順を実行してください。

5. mise ls で確認します。 設定ファイルのない python の行は、ツール専用のランタイムです。

6. mise.toml、mise.lock、.mise/locks/ をコミットします。 .mise/locks/ を git の無視対象にしてはいけません。 新しくクローンした環境では、手順 4 の厳密なインストールにこのディレクトリーが必要です。 mise trust の後、そのクローンで実行が必要な操作はこれだけです。

通常の mise lock は、記録済みの依存グラフを再利用します。 ツールのバージョンを変更せずに依存関係の修正を取り込むには、 mise lock --bump pypi:<tool> を実行してから、 手順 4 の厳密なインストールを行います。

手順：新規プロジェクトのセットアップ

1. 既存の mise.toml または .mise.toml がないことを確認します。 .mise.toml がある場合は、 作業を止めて移行手順を実行します。

2. リポジトリーのルートに mise.toml を作成します。

   [settings]
   disable_backends = ["ubi", "asdf"]
   lockfile = true
   
   [tools]
   

3. プロジェクトで使うすべてのランタイムと CLI について、 完全なバージョンを確認し （指定されていない場合はユーザーに尋ねます）、 ツールごとのバックエンド のルールに従ってエントリーを追加します。 例：

   [tools]
   node      = "20.11.1"
   go        = "1.22.4"
   terraform = "1.7.5"
   uv        = "0.13.6"
   "pypi:black"     = { version = "24.4.2", python = "3.14.10" }
   "npm:typescript" = "5.4.5"
   

   pypi: ツールまたは python のバージョン固定を使う場合は、 Python CLI：完全な分離 のガードブロックを追加します。 Python で書かれたプロジェクトでは、 Python で書かれたプロジェクト の venv エントリーも追加します。

4. mise trust を実行して、ファイルを承認します。

5. 手順：ロックとインストール を実行します。

手順：ツールを追加または固定する

1. リポジトリのルートに、必須の [settings] ブロックを含む mise.toml があることを確認します。 [settings] がない、または不完全な場合は、 追加します。
2. 固定する正確なバージョンを決めます （指定されていない場合は確認します）。
3. ツールごとのバックエンドのルールに従ってバックエンドを選びます。 mise がどのバックエンドを選ぶか不明な場合は、 mise registry <tool> を実行します。
4. [tools] の下にエントリーを追加します。 pypi: ツールには、Python CLI：完全な分離の規則を適用します。 python オプションを指定し、 uv を固定し、 ガードブロックを配置します。 Python で記述されたプロジェクトの python 固定には、 Python で記述されたプロジェクトの規則を適用します。
5. mise trust を実行します。 通常モードでは信頼設定はパスごとに保持されます。 paranoid モードでは mise がファイルをハッシュ化するため、変更のたびに再度信頼設定が必要です。 どちらのモードでも安全に対応できるよう、書き込みのたびに mise trust を実行します。
6. 手順：ロックしてインストールするを実行します。

手順：別のマネージャーから移行する

以下のいずれかが存在する場合に実行します。 .mise.toml、 .nvmrc、 .tool-versions、 .python-version、 .ruby-version、 ランタイムまたは CLI ツールを含む Brewfile、 volta または fnm の設定、 mise.toml 内の pipx.uvx、uvx_args、または pipx_args、 nvm install … のような README の行、 brew install <runtime>、 または pipx install …。

1. 別のシステムで管理されているすべてのツールを一覧にし、 バージョン範囲や latest の指定があれば、具体的な固定バージョンに解決します。
2. 移行計画をユーザーに提示します。 提案する mise.toml（[settings] と [tools] を含む）、 削除するファイル、 書き換えが必要なドキュメントの行を示します。 既存の .mise.toml がある場合： mise.toml に名前を変更し、必須の [settings] ブロックを追加するよう提案します。 .mise.toml をそのまま編集してはいけません。 uvx_args または pipx_args を使う Python CLI の場合： Python CLI：完全な分離のエントリーを提案し、pipx.uvx を削除します。
3. 変更を加える前に、明示的な確認を待ちます。
4. 確認後： mise.toml を書き込み、 古い設定ファイルを削除し、 ロックしてインストールするにある厳格なインストール方法を参照するようドキュメントを更新します。
5. mise trust を実行し、 手順：ロックしてインストールするを実行して、 削除したファイルも併せてコミットします。 mise prune --yes pipx:<tool> を実行すると、プレフィックスの変更後に残ったインストールを削除できます。

手順：許可されたどのバックエンドでもツールを利用できない場合

mise registry <tool> に ubi または asdf だけが表示される場合、 あるいは何も表示されない場合：

1. 停止します。
2. 状況をユーザーに伝えます。 ツール名、 mise が表示するバックエンド、 ubi と asdf を無効にするプロジェクトポリシーを示します。
3. 次の順序で代替案を提示します。
   • aqua / core / pypi / npm / cargo / gem のいずれかを利用できる別のツールを選ぶ。
   • ツールの言語が一致する場合は、言語ネイティブのバックエンド （pypi、npm、cargo、gem）を通じてインストールする。
   • 最後の手段として、このプロジェクトの disable_backends から asdf を削除することをユーザーに確認する。
4. ユーザーが asdf の例外を承認した場合： ubi は無効のままにし、 ツールのエントリーを書き込み、 ほかのバックエンドを確認したことと、いずれも利用できなかった理由を記録した TOML コメントをエントリーに追加します。 ubi を再度有効にしてはいけません。

報告

変更後、 書き込みまたは更新した mise.toml、 追加または固定したツール（バックエンドとバージョンを含む）、 各 pypi: ツールが実行する Python と、その依存グラフがロックされているかどうか、 削除した古いファイル、 mise.lock の状態（作成または更新）、 およびユーザーが次に実行するコマンド （mise trust、ロックしてインストールするに記載の厳格なインストール方法、mise ls）を伝えます。