aadebuger-ComfyUI-MiMoASR/INSTALL_NOTES.md

Install notes

The exhaustive companion to the README. Every error message we hit during real-world install, with the fix and why it happens.

If you're hitting an issue and just want it fixed, jump to Error → Fix table.

---

Why this model is annoying to install

Three structural issues, all in the upstream repo:

1. MimoAudio is not pip-installable. The repo lays the code out as src/mimo_audio/mimo_audio.py and uses imports of the form from src.mimo_audio.foo import bar. That only resolves if the repo root is on sys.path. The loader handles this via either the repo_path node field or the MIMO_ASR_REPO env var.

2. MimoAudio.__init__ takes positional args, not keywords. The HF model card shows MimoAudio(model_path="...", tokenizer_path="...") but the actual signature doesn't accept those kwargs. run_mimo_asr.py calls it positionally. v0.1.1+ of this node pack uses positional args to match.

3. Hard dependencies on specific transformers and flash-attn versions. The audio tokenizer encoder calls flash_attn_varlen_func with no SDPA fallback, and the modeling code uses the pre-all_tied_weights_keys API from transformers <=4.49. Both must be addressed before the model can run.

---

Compatibility matrix

Component	Upstream pin	What you probably have	What you need
Python	3.12	3.10–3.13	3.10+ (3.13 works)
torch	2.6.0	2.4–2.11	any recent, don't downgrade
transformers	4.49.0	4.50–5.x	must downgrade to 4.49.0
tokenizers	implicit	varies	>=0.21,<0.22
flash-attn	2.7.4.post1	none	any working build
CUDA toolkit	≥12.0	12.4–12.6	matches nvcc --version

---

Disk space (HF cache)

MiMo-V2.5-ASR is 8B params. The safetensors are stored in F32 on the Hub (~32 GB), and HF stages a full copy in HF_HOME before symlinking to your --local-dir. If your root partition is small:

# Add to ~/.bashrc so every shell sees it
export HF_HOME=/big_disk/hf_cache
mkdir -p "$HF_HOME"

Symptom of not doing this: OSError: [Errno 28] No space left on device half-way through the download.

---

transformers downgrade — what to expect

uv pip freeze > ~/pip_freeze_before_mimo_$(date +%Y%m%d).txt
uv pip install "transformers==4.49.0" "tokenizers>=0.21,<0.22" --force-reinstall

This will almost certainly affect other ComfyUI custom nodes.

Custom node	Risk	Notes
Pure SDXL / Florence2 workflows	Low	Uses diffusers, mostly unaffected.
ComfyUI-VibeVoiceASR	Medium	Qwen2 backbone; may need adjustment.
ComfyUI-PaddleOCRVL	High	PaddleOCR-VL expects newer transformers.
Sonic / Qwen3TTS-class nodes	Very high	Often pinned to transformers >=4.57.
Anything with HF auto-class registration in 5.x	Very high	API renames.

Strategy A: accept the conflict. Use one ComfyUI install for MiMo ASR, restart with the other version when you need the other nodes.

Strategy B: dedicated ComfyUI for MiMo. Recommended if you use the high-risk nodes daily.

# Clone the venv (cheap because Python deps share .so files via inodes)
cd /mnt/modelall
cp -r ComfyUI ComfyUI-MiMo
cd ComfyUI-MiMo && source .venv/bin/activate
uv pip install "transformers==4.49.0" "tokenizers>=0.21,<0.22" --force-reinstall

# Launch on a different port
python main.py --listen 0.0.0.0 --port 8189

Then point the CLI at the dedicated instance: --ip SERVER --port 8189.

Strategy C: roll back if the downgrade breaks too much.

uv pip install -r ~/pip_freeze_before_mimo_*.txt --force-reinstall

---

Building flash-attn from source

The precompiled flash-attn==2.7.4.post1 wheel only matches one exact combo: cu12 + torch 2.6 + Python 3.12 + cxx11abi=False. Anything else needs a source build.

Prerequisites

# Tooling
uv pip install ninja packaging

# CUDA toolkit must be present and findable.
# Default Ubuntu location is /usr/local/cuda-XX.X — adjust to yours.
ls /usr/local/cuda-12.6/bin/nvcc   # must exist

If nvcc is missing, install the matching toolkit:

sudo apt install cuda-toolkit-12-6   # adjust to your CUDA version

Build

cd ComfyUI && source .venv/bin/activate

export CUDA_HOME=/usr/local/cuda-12.6
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

# GPU compute capability — set this to avoid building for archs you don't have
#   3090 = 8.6,  A100 = 8.0,  4090 = 8.9,  H100 = 9.0
export TORCH_CUDA_ARCH_LIST="8.6"

# Parallel jobs. Each nvcc job uses ~2 GB RAM. Tune to your hardware.
export MAX_JOBS=4

# Build (will take 20-40 min on a 3090 host)
nohup uv pip install flash-attn --no-build-isolation \
    > ~/flash_attn_build.log 2>&1 &
tail -f ~/flash_attn_build.log

When it finishes, the log ends with something like Successfully installed flash-attn-X.Y.Z. Verify:

python -c "from flash_attn import flash_attn_varlen_func; print(flash_attn_varlen_func)"
# Must print: <function flash_attn_varlen_func at 0x...>

Common build failures

Log message	Fix
nvcc: command not found	export PATH=$CUDA_HOME/bin:$PATH
cannot find -lcuda	export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
g++: fatal error: cuda_runtime.h: No such file	Install matching cuda-toolkit-XX-X
nvcc fatal: Unsupported gpu architecture 'compute_XX'	Wrong TORCH_CUDA_ARCH_LIST; query yours with python -c "import torch; print(torch.cuda.get_device_capability(0))" (returns e.g. (8, 6) → use "8.6")
g++: internal compiler error: Killed (program cc1plus)	Out of RAM. Reduce MAX_JOBS
Build hangs at "Building wheel" with no progress	Patience — first nvcc compile step has no output for ~5 min

If the build finishes but python -c "from flash_attn import flash_attn_varlen_func" returns None instead of a function, the install silently failed. Re-check the log.

---

sys.path injection — how it actually works

MimoAudio imports look like:

from src.mimo_audio.mimo_audio import MimoAudio

So the parent of src/ must be on sys.path — i.e., the repo root, the directory containing run_mimo_asr.py. Not src/mimo_audio/ itself. The loader does:

sys.path.insert(0, str(repo_root))

Two ways to feed repo_root to the loader:

• Per-node: fill in the repo_path field on the MiMoASRLoader node.
• Globally: set MIMO_ASR_REPO=/path/to/repo before launching ComfyUI. Recommended — your workflows then load with repo_path blank.

Symptoms of getting this wrong:

• repo_path blank and env unset → RuntimeError: MiMo ASR repo path is empty.
• Path points at src/mimo_audio/ instead of the repo root → RuntimeError: Did not find src/mimo_audio/ under <path>.
• Path points at a partial clone (no src/) → same error. Fix with git submodule update --init --recursive.

---

Error → Fix table

Reference card. Each row is a real error message you might see, with the cause and the fix.

Install / configuration errors

Symptom	Cause	Fix
RuntimeError: MiMo ASR repo path is empty.	Neither repo_path node field nor MIMO_ASR_REPO env var is set.	Clone the upstream repo; set the env var or the node field.
RuntimeError: Did not find src/mimo_audio/ under <path>.	Wrong path, or empty / partial clone.	Verify ls <path>/src/mimo_audio/. Run git submodule update --init --recursive inside the clone if needed.
RuntimeError: MiMo-V2.5-ASR model path does not exist: ...	Step 3 skipped, or relative path used.	Download via hf download; pass an absolute path to the node.
RuntimeError: MiMo-Audio-Tokenizer path does not exist: ...	Same as above for the tokenizer.	hf download XiaomiMiMo/MiMo-Audio-Tokenizer --local-dir ...
ModuleNotFoundError: No module named 'src' (at first load)	sys.path injection happened but the path is wrong.	Verify <repo_path>/src/mimo_audio/ exists.

Python dep errors

Symptom	Cause	Fix
AttributeError: 'MiMoAudioTokenizer' object has no attribute 'all_tied_weights_keys'. Did you mean: '_tied_weights_keys'?	transformers >= 4.50 changed the tied-weights API. MiMo's modeling code uses the old name.	Downgrade: uv pip install "transformers==4.49.0" "tokenizers>=0.21,<0.22" --force-reinstall
TypeError: MimoAudio.__init__() got an unexpected keyword argument 'tokenizer_path'	You're on v0.1.0 of this node pack; it calls MimoAudio(model_path=..., tokenizer_path=...). The actual signature is positional.	Upgrade to v0.1.1+ of this node pack.
ImportError: cannot import name 'XXX' from 'transformers'	Some other custom node forced transformers to a newer or older version after MiMo was working.	Re-run the step 4 install. Consider Strategy B (dedicated ComfyUI).

Runtime errors

Symptom	Cause	Fix
TypeError: 'NoneType' object is not callable deep in mimo_audio_tokenizer/modeling_audio_tokenizer.py at flash_attn_varlen_func(...)	flash-attn not installed; upstream binds flash_attn_varlen_func = None on ImportError and uses it anyway.	Install per Step 5 of the README. There is no SDPA fallback.
RuntimeError: CUDA out of memory during load	Other models still resident in VRAM.	Restart ComfyUI, or use ComfyUI-Manager's "Free model and node cache".
RuntimeError: FlashAttention only supports fp16 and bf16 dtype	Loader's dtype detection failed; the model is in fp32.	Open an issue with your torch.__version__ and the full traceback.
Empty transcript output (no error)	PreviewAny node missing from your server, but the workflow expects it.	Install rgthree-comfy, or use `ShowText
First run takes 30–60 s	Normal — loading 8B weights from disk.	Subsequent runs in the same ComfyUI session are instant thanks to _MODEL_CACHE.

---

End-to-end smoke test

After install, run this from the client side (your dev machine, not the server):

# 0. ComfyUI reachable
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://SERVER:8188/

# 1. Nodes registered
curl -s http://SERVER:8188/object_info | python3 -c "
import json, sys
d = json.load(sys.stdin)
for n in ('MiMoASRLoader', 'MiMoASRTranscribe', 'LoadAudio', 'PreviewAny'):
    print(f'  {n}: {\"OK\" if n in d else \"MISSING\"}')"

# 2. Dump a workflow without submitting (verifies argparse / paths)
uv run python cli/mimo_asr_cli.py /path/to/test.wav --ip SERVER \
    --model-path /big_disk/models/MiMo-V2.5-ASR \
    --tokenizer-path /big_disk/models/MiMo-Audio-Tokenizer \
    --repo-path /opt/repos/MiMo-V2.5-ASR \
    --dump-workflow /tmp/wf.json --no-run

# 3. Inspect — load /tmp/wf.json in ComfyUI's UI via "Load" to verify connections

# 4. Real run
uv run python cli/mimo_asr_cli.py /path/to/test.wav --ip SERVER \
    --model-path /big_disk/models/MiMo-V2.5-ASR \
    --tokenizer-path /big_disk/models/MiMo-Audio-Tokenizer \
    --repo-path /opt/repos/MiMo-V2.5-ASR

On a 3090, expect:

• First run: 30–60 s (model load) + 2–4 s (inference)
• Subsequent runs in same session: 2–4 s
• VRAM after load: ~17 GB
• VRAM at peak: ~20–22 GB

If your numbers are wildly off, file an issue with nvidia-smi output and your torch / transformers / flash-attn versions.