# MuseTalkインストール完全攻略 — mmcv/mmdet/mmpose依存地獄・CUDA不一致・新GPU対応・頻出エラー全解決

> MuseTalkのセットアップで誰もが詰まるmmcv/mmdet/mmposeの依存地獄を、公式準拠の『動く組み合わせ』で一発解決。Python 3.10/PyTorch 2.0.1/CUDA 11.7/mmcv 2.0.1の正しい導入順、No module named mmcv._ext・CUDA is not available・libGL.so.1欠落・onnxruntimeのCPUフォールバック・新GPU(Blackwell)対応まで、原因と対策を網羅し、Dockerでの再現性確保まで示します。

- 公開日: 2026-06-25
- 著者: 友田 陽大
- タグ: MuseTalk, トラブルシューティング, mmcv, CUDA, Python, GPU, 環境構築, リップシンク
- URL: https://tomodahinata.com/blog/musetalk-installation-troubleshooting-mmcv-mmdet-mmpose-cuda

## 要点

- MuseTalkが難しいのはモデルではなくmmlab系の依存。mmcv/mmdet/mmposeはバージョンが密結合で、1つ上げると全部壊れる。公式の固定版をmim経由で入れるのが唯一の安定解
- 正しい導入順は『システム依存→Python3.10環境→PyTorch2.0.1(cu117)→requirements→mim install mmcv==2.0.1/mmdet==3.1.0/mmpose==1.1.0→重み取得』。順番を守ることが9割
- 頻出エラーは原因が決まっている：No module named mmcv._ext=ビルド不一致、CUDA is not available=CPU版torch/ドライバ不一致、libGL.so.1=libgl1欠落、激遅=onnxruntimeのCPUフォールバック
- 新GPU(Blackwell/RTX 50xx)は公式の固定版(cu117)では動かないことがある。コミュニティ報告では新しいtorch＋Python/mediapipeのパッチが要る。要一次情報確認
- 二度と環境構築で消耗しないために、動いた組み合わせをDockerに焼き込む。再現性こそが本番運用の前提になる

---

## この記事のゴール

[MuseTalk](/blog/musetalk-realtime-lip-sync-production-guide) を試そうとして、**モデルの中身に到達する前に環境構築で何日も溶かす**——これは「あるある」を超えて、ほぼ通過儀礼です。原因は 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](https://github.com/TMElyralab/MuseTalk)）準拠の手順です。**順番を守ること**が成功の9割です。

### Step 0：システム依存（Ubuntu系）

```bash
# 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 の隔離環境

```bash
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 ビルドを“明示”）

```bash
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：アプリ依存

```bash
pip install -r requirements.txt
```

### Step 4：mmlab を `mim` で固定版インストール（最重要）

```bash
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：モデル重みの取得

```bash
# 公式スクリプト（Linux）。Windowsは download_weights.bat
sh download_weights.sh
```

最終的なツリー（主要分）：

```text
./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：動作確認（必ずやる）

```bash
# ① 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起動するが顔が検出されない | 横顔/遮蔽/複数顔/低解像度 | 素材を**正面・単一顔**に。前処理で顔検出ガード（[落とし穴章](/blog/musetalk-realtime-lip-sync-production-guide#本番で必ず詰まる落とし穴と回復性設計)） |

### 深掘り：`No module named 'mmcv._ext'`（最頻出）

`mmcv._ext` は **mmcv のC++/CUDA拡張**。これが無い＝**今の torch/CUDA に合ったビルドが入っていない**サインです。やることは決まっています。

```bash
# 中途半端な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`

切り分けはこの順で。

```bash
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](https://github.com/TMElyralab/MuseTalk/issues) を一次情報として確認**してください。本番では、**動いた組み合わせを即座にDockerに固定**して、二度と解決し直さないのが鉄則です。

---

## 恒久対策：Dockerで「もう二度と」やらない

一度動く組み合わせに辿り着いたら、**それをDockerに焼き込んで再現性を担保**します。これが、依存地獄から永久に抜ける唯一の方法です。

```dockerfile
# 動いた組み合わせを固定（詳細は本番デプロイ記事へ）
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本番デプロイ実践](/blog/musetalk-self-host-production-deployment-docker-gpu-autoscaling)にまとめています。

---

## よくある質問（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](/blog/musetalk-realtime-lip-sync-production-guide#使い方a試すだけなら-apifalai--replicate自前gpu不要)で品質を確認し、**本気で運用する段階でDocker化**するのが最短ルートです。

---

## まとめ：順番と固定版、そしてDocker

MuseTalk のインストールは、**コツさえ知れば一本道**です。

1. **システム依存（libgl1/ffmpeg）→ Python3.10 → PyTorch2.0.1(cu117) → requirements → mim install → 重み取得**、の順番を守る。
2. **mmcv==2.0.1 / mmdet==3.1.0 / mmpose==1.1.0** を **`mim` で固定**。`pip install mmcv` の最新は地雷。
3. エラーは原因が決まっている。**早見表**で潰す（`mmcv._ext`＝ビルド不一致、`CUDA is not available`＝CPU版torch）。
4. 新GPUは公式固定版の外。**Issueを一次情報に**、動いたらすぐ固定。
5. **動いた組み合わせはDockerに焼き込む**。再現性が本番運用の前提。

ここまで来れば、もう環境構築で消耗しません。次は**実際に使う**——[MuseTalk完全ガイド](/blog/musetalk-realtime-lip-sync-production-guide)で仕組みとチューニングへ進んでください。

> 私は、本稿の環境構築・Docker化を**実際の本番GPUパイプラインで運用**しています。「環境構築でいつも詰まる」「再現性のある本番環境を作りたい」なら、[実績](/case-studies/ai-video-localization-lipsync)をご覧のうえご相談ください。**一人 × 生成AI**で、PoCから本番運用まで一気通貫で、速く・安く・安全に作ります。

---

## 出典・関連リソース

- **MuseTalk公式**：[GitHub（README・download_weights・requirements）](https://github.com/TMElyralab/MuseTalk) ／ [Issues（新GPU対応等の一次情報）](https://github.com/TMElyralab/MuseTalk/issues)
- **OpenMMLab**：mmcv / mmdet / mmpose（`mim` での導入が公式推奨）
- **使い方・チューニング**：[MuseTalk完全ガイド](/blog/musetalk-realtime-lip-sync-production-guide)
- **本番化**：[MuseTalk本番デプロイ実践（Docker/GPU/オートスケール）](/blog/musetalk-self-host-production-deployment-docker-gpu-autoscaling)
- **モデル選定**：[AIリップシンク・トーキングヘッド モデル選定ガイド2026](/blog/ai-lip-sync-talking-head-model-selection-guide-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）は本稿執筆時点の公式準拠です。