この記事のゴール
MuseTalk を試そうとして、モデルの中身に到達する前に環境構築で何日も溶かす——これは「あるある」を超えて、ほぼ通過儀礼です。原因は MuseTalk 本体ではなく、顔・ポーズ検出に使う mmlab エコシステム（mmcv / mmdet / mmpose）の依存地獄にあります。
本稿は、その地獄を公式準拠の「動く組み合わせ」で一発で抜けるための実践ガイドです。正しい導入順を示し、頻出エラーを原因ごとに潰し、最後はDockerで二度と環境構築しないところまで持っていきます。「No module named 'mmcv._ext' で心が折れた」人が、今日中に推論を回せる状態を目指します。
筆者について（信頼性の開示）：私は MuseTalk を含む複数のリップシンクモデルをセルフホストで本番運用しています。本稿のエラー対処は、ドキュメントの引き写しではなく、実際にこの環境を何度も組み直して踏んだ地雷の記録です。
30秒のまとめ（結論を先に）
| 論点 | 結論 |
|---|---|
| なぜ難しい | MuseTalk本体ではなくmmlab系（mmcv/mmdet/mmpose）の依存が密結合だから |
| 唯一の安定解 | 公式の固定版を mim 経由で入れる。pip install mmcv で最新を入れると壊れる |
| 正しい順番 | システム依存 → Python3.10 → PyTorch 2.0.1(cu117) → requirements → mim install → 重み取得 |
| 固定版 | mmcv==2.0.1 / mmdet==3.1.0 / mmpose==1.1.0（この3つはセット） |
| 頻出エラー | mmcv._ext欠落＝ビルド不一致、CUDA is not available＝CPU版torch/ドライバ、libGL.so.1＝libgl1欠落 |
| 新GPU | Blackwell(RTX 50xx)等は公式の固定版で動かないことあり。新しいtorch＋パッチが要る（要確認） |
| 恒久対策 | Dockerに焼き込む。再現性を担保し二度と消耗しない |
なぜMuseTalkのインストールは難しいのか
MuseTalk は内部で dwpose（顔・体ポーズ） や 顔検出/パース を使い、それらが mmlab（OpenMMLab）のライブラリ群——mmcv・mmdet・mmpose——に依存します。この3つは互いのバージョンが強く結合しており、
mmcvは PyTorch と CUDA のバージョンに合わせてC++/CUDA拡張をビルドする（mmcv._ext）。mmdet/mmposeは特定のmmcvバージョン範囲しか受け付けない。
つまり、「torch ↔ cuda ↔ mmcv ↔ mmdet ↔ mmpose」の5つが全部噛み合って初めて動く。1つでも最新に上げると、ドミノで崩れます。これが「pip install mmcv したら mmdet が import で落ちる」の正体です。
結論：自分でバージョンを解決しようとしない。公式が検証した固定の組み合わせを、正しい順番で入れる。 これに尽きます。
ゴールデンパス：この順番で、この版を入れる
公式（GitHub README）準拠の手順です。順番を守ることが成功の9割です。
Step 0：システム依存（Ubuntu系）
# OpenCVが必要とするlibGLと、動画I/Oのffmpeg
sudo apt-get update
sudo apt-get install -y libgl1 libglib2.0-0 ffmpeg
libgl1を入れ忘れると、後でImportError: libGL.so.1: cannot open shared object fileで必ず転びます。先に入れておきます。
Step 1：Python 3.10 の隔離環境
conda create -n MuseTalk python==3.10
conda activate MuseTalk
3.10 を守る。3.11/3.12 だと mmlab 系のホイールが見つからず詰まることがあります（新GPUの例外は後述）。
Step 2：PyTorch 2.0.1（CUDA 11.7 ビルドを“明示”）
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 \
--index-url https://download.pytorch.org/whl/cu117
ここで
--index-urlを省くと、CPU版や別CUDA版の torch が入り、後でtorch.cuda.is_available()がFalseになって「動くけど激遅」or「GPUを使わない」状態に陥ります。CUDA 11.7 を明示します。
Step 3：アプリ依存
pip install -r requirements.txt
Step 4：mmlab を mim で固定版インストール（最重要）
pip install -U openmim
mim install "mmengine"
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
mim install "mmpose==1.1.0"
なぜ
mimか：mim（OpenMMLab Installs More）は、今の torch/CUDA に合ったmmcvのビルド済みホイールを解決して入れてくれます。pip install mmcvだと最新版やソースビルドを掴んでmmcv._extのビルドに失敗しがち。必ずmimで、バージョンを固定して入れます。mmcv → mmdet → mmposeの順も守ります。
Step 5：モデル重みの取得
# 公式スクリプト（Linux）。Windowsは download_weights.bat
sh download_weights.sh
最終的なツリー（主要分）：
./models/
├── musetalkV15/ (unet.pth, musetalk.json) # 最新v1.5本体
├── musetalk/ (pytorch_model.bin, ...) # v1.0
├── sd-vae/ (diffusion_pytorch_model.bin, config.json)
├── whisper/ (pytorch_model.bin, ...) # 音声特徴
├── dwpose/ (dw-ll_ucoco_384.pth)
├── face-parse-bisent/ (79999_iter.pth, resnet18-5c106cde.pth)
└── syncnet/ (latentsync_syncnet.pt) # 同期評価
Step 6：動作確認（必ずやる）
# ① GPUが見えているか（False なら Step 2 をやり直す）
python -c "import torch; print('cuda:', torch.cuda.is_available())"
# ② mmcvのCUDA拡張が読めるか（ここが通れば山は越えた）
python -c "from mmcv.ops import RoIAlign; print('mmcv._ext OK')"
# ③ デモ推論（v1.5・通常）
sh inference.sh v1.5 normal
cuda: True と mmcv._ext OK が出れば、依存地獄は突破です。
頻出エラー早見表（原因 → 対策）
実際に出るエラーは、ほぼこの表で説明できます。
| エラー / 症状 | 原因 | 対策 |
|---|---|---|
No module named 'mmcv._ext' | mmcv が今の torch/CUDA と不一致のビルド | pip uninstall mmcv mmcv-full -y 後、mim install "mmcv==2.0.1" で入れ直す |
mmdet / mmpose が import で落ちる | mmcv のバージョン不整合 | 3つを固定版で揃える（2.0.1 / 3.1.0 / 1.1.0）。順番も mmcv→mmdet→mmpose |
torch.cuda.is_available() が False | CPU版torchが入った / ドライバ不一致 | Step 2 を --index-url .../cu117 で入れ直す。nvidia-smi でドライバ確認 |
ImportError: libGL.so.1 | システムに libgl1 が無い | sudo apt-get install -y libgl1 libglib2.0-0 |
ffmpeg: command not found / 動画書き出し失敗 | ffmpeg 未導入 / パス不明 | apt install ffmpeg、Windowsは --ffmpeg_path を渡す |
| 推論が異常に遅い（GPUなのにCPU並み） | onnxruntime-gpu のCPUフォールバック or torchがCPU | onnxruntime-gpu と CUDA/cuDNN の整合を確認。①の torch CUDA も再確認 |
CUDA out of memory | 長尺/大バッチ/fp32 | --use_float16 を付ける、--batch_size を下げる、長尺はセグメント分割 |
重みが見つからない（FileNotFoundError） | ダウンロード未完 / パス違い | download_weights.sh を再実行し、models/ のツリーを確認 |
huggingface のDLが途中で止まる | ネットワーク/認証 | 再実行（レジューム）、必要なら huggingface-cli login・ミラー利用 |
| Gradio起動するが顔が検出されない | 横顔/遮蔽/複数顔/低解像度 | 素材を正面・単一顔に。前処理で顔検出ガード（落とし穴章） |
深掘り：No module named 'mmcv._ext'（最頻出）
mmcv._ext は mmcv のC++/CUDA拡張。これが無い＝今の torch/CUDA に合ったビルドが入っていないサインです。やることは決まっています。
# 中途半端なmmcvを完全に消してから、mimで“今の環境に合う”版を入れ直す
pip uninstall -y mmcv mmcv-full mmcv-lite
mim install "mmcv==2.0.1"
python -c "from mmcv.ops import RoIAlign; print('OK')"
ソースからビルドし始めたら危険信号です（コンパイラ/CUDAツールキットの沼に入る）。mim がビルド済みホイールを見つけられるよう、torch を先に正しく入れておくのが効きます。
深掘り：CUDA is not available
切り分けはこの順で。
nvidia-smi # ドライバ/GPUが見えるか。出なければホスト側の問題（ドライバ未導入）
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
# 期待: 2.0.1+cu117 / 11.7 / True
torch.version.cuda が None ならCPU版が入っている＝Step 2 を --index-url 付きでやり直し。nvidia-smi が出ないならホストのNVIDIAドライバを先に直します（コンテナならホスト側）。
新しいGPU（Blackwell / RTX 50xx）で動かないとき
公式の固定版は CUDA 11.7 / PyTorch 2.0.1 前提です。ところが、**新しいGPUアーキテクチャ（例：Blackwell世代、RTX 50xx、compute capability sm_120 など）**は、cu117 ビルドの torch では未対応で、CUDA error: no kernel image is available for execution on the device のようなエラーになることがあります。
この場合、公式の固定版から外れる対応が必要になります。コミュニティの報告では——
- 新しい CUDA 対応の PyTorch（より新しい cu12x ビルド）に上げる。
- それに伴い Python を 3.12 等へ、mediapipe 等の依存にパッチを当てる、といった調整が要る。
⚠️ 正確性のための注記：これは公式手順の外であり、mmcv/mmdet/mmpose の対応版を再解決する必要があります（torchを上げると mmcv も合わせる）。バージョンの最新の正解は動くターゲットなので、公式リポジトリのIssue/Discussion を一次情報として確認してください。本番では、動いた組み合わせを即座にDockerに固定して、二度と解決し直さないのが鉄則です。
恒久対策：Dockerで「もう二度と」やらない
一度動く組み合わせに辿り着いたら、それをDockerに焼き込んで再現性を担保します。これが、依存地獄から永久に抜ける唯一の方法です。
# 動いた組み合わせを固定（詳細は本番デプロイ記事へ）
FROM nvidia/cuda:11.7.1-cudnn8-runtime-ubuntu22.04
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
python3.10 python3-pip git ffmpeg libgl1 libglib2.0-0 \
&& rm -rf /var/lib/apt/lists/*
RUN pip3 install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 \
--index-url https://download.pytorch.org/whl/cu117
COPY requirements.txt .
RUN pip3 install -r requirements.txt \
&& pip3 install -U openmim \
&& mim install "mmengine" "mmcv==2.0.1" "mmdet==3.1.0" "mmpose==1.1.0"
Docker・GPUサービング・オートスケール・コスト最適化を含む本番デプロイの全体像は、MuseTalk本番デプロイ実践にまとめています。
よくある質問（FAQ）
Q. pip install mmcv ではダメなの？
A. ダメなことが多いです。最新版やソースビルドを掴み、mmcv._ext のビルドに失敗したり mmdet/mmpose と不整合になります。必ず mim でバージョン固定（2.0.1）して入れてください。
Q. Python 3.11 / 3.12 で入れたい。 A. 公式は 3.10 推奨です。新しいPythonは mmlab のホイールが見つからず詰まりがち。新GPUでやむを得ず torch を上げる場合を除き、3.10 を守るのが安全です。
Q. Windowsでも動く？
A. 動きます。download_weights.bat、ffmpeg は配布バイナリを --ffmpeg_path で渡します。ただし mmlab のビルド事情は Linux の方が素直なので、WSL2 もしくは Docker を推奨します。
Q. CPUだけでも動かせる？
A. 動かせなくはありませんが極端に遅い（公式でも RTX 3050 Ti で8秒動画が約5分=fp16）。実用にはGPUが前提です。torch.cuda.is_available() が True であることを必ず確認してください。
Q. macOS (Apple Silicon) では？ A. CUDA前提のため、素直ではありません。検証は Linux + NVIDIA GPU（クラウドのGPUインスタンス含む）か、サードパーティAPI（fal.ai等）を使うのが現実的です。
Q. 結局、最短で試す方法は？ A. 環境構築を飛ばしたいなら、まずサードパーティAPIで品質を確認し、本気で運用する段階でDocker化するのが最短ルートです。
まとめ：順番と固定版、そしてDocker
MuseTalk のインストールは、コツさえ知れば一本道です。
- システム依存（libgl1/ffmpeg）→ Python3.10 → PyTorch2.0.1(cu117) → requirements → mim install → 重み取得、の順番を守る。
- mmcv==2.0.1 / mmdet==3.1.0 / mmpose==1.1.0 を
mimで固定。pip install mmcvの最新は地雷。 - エラーは原因が決まっている。早見表で潰す（
mmcv._ext＝ビルド不一致、CUDA is not available＝CPU版torch）。 - 新GPUは公式固定版の外。Issueを一次情報に、動いたらすぐ固定。
- 動いた組み合わせはDockerに焼き込む。再現性が本番運用の前提。
ここまで来れば、もう環境構築で消耗しません。次は実際に使う——MuseTalk完全ガイドで仕組みとチューニングへ進んでください。
私は、本稿の環境構築・Docker化を実際の本番GPUパイプラインで運用しています。「環境構築でいつも詰まる」「再現性のある本番環境を作りたい」なら、実績をご覧のうえご相談ください。一人 × 生成AIで、PoCから本番運用まで一気通貫で、速く・安く・安全に作ります。
出典・関連リソース
- MuseTalk公式：GitHub（README・download_weights・requirements） ／ Issues（新GPU対応等の一次情報）
- OpenMMLab：mmcv / mmdet / mmpose（
mimでの導入が公式推奨） - 使い方・チューニング：MuseTalk完全ガイド
- 本番化：MuseTalk本番デプロイ実践（Docker/GPU/オートスケール）
- モデル選定：AIリップシンク・トーキングヘッド モデル選定ガイド2026
※ バージョン・対応GPU・依存関係は更新されます。特に新しいGPUへの対応は流動的なので、必ず公式リポジトリのIssue/READMEを一次情報として確認してください。本稿の固定版（Python 3.10 / PyTorch 2.0.1 / CUDA 11.7 / mmcv 2.0.1 / mmdet 3.1.0 / mmpose 1.1.0）は本稿執筆時点の公式準拠です。