はじめに
WHAM は、単眼動画から 3D human motion を推定し、人物の移動軌跡まで含めてワールド座標系で扱えるのが面白いプロジェクトです。
自分はいまダンス動画から 3DCG やモーションデータを AI 検出により生成する自前研究テーマ・プロジェクトに取り組んでおり、後続の研究開発工程でも、動画から SMPL パラメータを抽出する基盤の一つとして WHAM を使っています。
ただ、実際に環境構築を始めると README どおりにはなかなか進みません。WHAM は PyTorch 1.11.0 + CUDA 11.3 世代を前提にしていて、2026 年時点の Ubuntu / Python / MKL / CUDA 環境とは少しずつズレています。特に mmcv==1.3.9、ViTPose、DPVO のような「古い Python パッケージ + ネイティブ拡張 + CUDA ビルド」が絡む部分は、そのままだと止まりやすいです。
この記事では、まず Pixi 仮想環境で WHAM をどこまで再現できるか試し、その後 Docker に切り替えて最終的にビルドを通した記録をまとめます。先に結論を書くと、WHAM 本体の Python 依存を切り分けるなら Pixi は便利ですが、DPVO まで含めて安定して再現するなら Docker の方が圧倒的に楽でした。
先に結論
結論はかなりシンプルです。WHAM のように「古い PyTorch + CUDA 拡張 + C++/CUDA ビルド」が混ざった構成では、Docker の nvidia/cuda:*devel* イメージを土台にした方が安定します。
一方で Pixi が無意味だったわけではありません。PyTorch3D、mmcv==1.3.9、ViTPose までを切り分けながら入れていく段階ではかなり便利で、どこから先が Python の依存問題で、どこから先が CUDA toolkit / headers の問題なのかを見分けるのに役立ちました。
何が難しいのか
WHAM の前提は PyTorch 1.11.0 と CUDA 11.3 世代です。この時点で、2026 年の一般的な Linux マシンに入っている CUDA 12.x 系や、更新された MKL・Python パッケージ群とは世代差があります。
さらに WHAM 本体だけでなく、mmcv==1.3.9、ViTPose、DPVO といった周辺依存もあります。単に pip install -r requirements.txt で終わる構成ではなく、特に DPVO は CUDA 拡張をビルドするので、PyTorch のランタイム互換だけでは足りません。ビルド時に見える nvcc、CUDA headers、GCC 系ツールチェーンまで揃っている必要があります。
まずは Pixi で試した
最初は Docker より軽く扱える環境として Pixi を使ってみました。Python 3.9、PyTorch 1.11.0、TorchVision 0.12.0、TorchAudio 0.11.0、PyTorch3D までは比較的順調に入りました。さらに mmcv==1.3.9 は --no-build-isolation 付きで導入し、ViTPose も editable install で通せました。
この段階では、「WHAM 本体の Python 側依存は Pixi でもかなり再現できるな」という感触でした。少なくとも README をただなぞるよりは、依存の分離と失敗箇所の特定がしやすかったです。
Pixi 版で最初に止まったポイント
問題が出たのは third-party/DPVO の pip install . でした。最初に出たのは、次の CUDA バージョン不整合エラーです。
RuntimeError:
The detected CUDA version (12.6) mismatches the version that was used to compile
PyTorch (11.3). Please make sure to use the same CUDA versions.
これは、PyTorch の CUDA 拡張ビルドが ホスト側の CUDA toolkit 12.6 を検出した一方で、インストール済みの PyTorch が CUDA 11.3 版 だったために起きました。
PyTorch の prebuilt バイナリは実行時には同梱ランタイムで動けますが、torch.utils.cpp_extension を使って C++/CUDA 拡張をビルドする場面では、ローカルの nvcc や CUDA headers を参照します。つまり、ホストに入っている CUDA toolkit のバージョン差が、そのままビルドエラーとして出てきます。
そこを回避したら次の壁があった
この mismatch を避けるために、Pixi 環境内の nvcc を使わせる方向に切り替えました。CUDA_HOME=$CONDA_PREFIX や TORCH_CUDA_ARCH_LIST を設定し、system CUDA 12.6 を見ないように調整したところ、今度は次のエラーで止まりました。
cc1plus: fatal error: cuda_runtime.h: No such file or directory
これは、nvcc 自体は見つかっているけれど、CUDA Runtime の開発ヘッダが揃っていないことを意味します。
つまり Pixi 版では、何もしないと system CUDA 12.6 を拾って PyTorch 11.3 と不整合になり、Pixi 側の nvcc を使わせると今度は cuda_runtime.h などのヘッダ不足で止まる、という二段階の壁がありました。
なぜ Pixi だけでは厳しかったのか
ここで重要なのは、「Pixi が悪い」という話ではないことです。問題は、CUDA 11.3 世代の build toolchain を 2026 年の conda/Pixi 環境だけで綺麗に再現するのが難しいという点にあります。
最近の CUDA は runtime・compiler・headers が細かく分割されたパッケージとして提供されますが、古い CUDA 11.3 世代では、必要な部品が solver 上で綺麗に揃わなかったり、nvcc だけ取れてもヘッダ一式が欠けたりするケースがあります。そのため、Pixi は Python パッケージ管理には強い一方で、古い CUDA 拡張ビルドを完全再現するには少し厳しい、というのが今回の実感でした。
そこで Docker に切り替えた
Pixi 版でどこまで進めるか試した結果、WHAM 本体の依存確認には役立つ一方、DPVO を含むフル構成の再現には Docker の方が向いていると判断しました。理由は単純で、Docker なら WHAM が前提としている CUDA 11.3 世代の build environment をそのまま閉じ込められるからです。
とくに nvidia/cuda:11.3.1-cudnn8-devel-ubuntu20.04 のような devel イメージは、runtime だけでなく headers と build tools を含むので、CUDA 拡張をソースからビルドする用途に向いています。
Docker 版でも最初から一発では通らなかった
Docker 版も、最初から一発で通ったわけではありません。まず DPVO 周辺の対応として cudatoolkit-dev を conda で追加しようとしたところ、post-link スクリプト内で NVIDIA の .run installer が動き、共有ライブラリ不足で失敗しました。
ここで分かったのは、ベースイメージがすでに CUDA 11.3 の devel 環境を持っているなら、cudatoolkit-dev をさらに重ねる必要はないということでした。実際、この行を削除すると次の段階まで進めました。
TORCH_CUDA_ARCH_LIST の設定も必要だった
DPVO のビルドでは、TORCH_CUDA_ARCH_LIST を明示しないと torch.utils.cpp_extension 内でターゲットアーキテクチャの推定が失敗し、最終的に IndexError で落ちました。
そのため Dockerfile では、次のように設定しました。
ENV TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6"
CUDA 11.3 世代で安全に扱える範囲に絞るため、Turing / Ampere 向けの値だけを入れています。少なくとも PyTorch 1.11.0 + cu113 という前提では、この指定でビルドが安定しました。
2026 年のライブラリ事情に合わせた修正も必要だった
Docker 版で最終的に効いたのは、CUDA まわりだけではありませんでした。2026 年時点では、周辺ライブラリの更新による別の問題も出ます。
ひとつは mmcv==1.3.9 導入時の libtorch_cpu.so: undefined symbol: iJIT_NotifyEvent です。これは MKL 2024.1 以降との組み合わせで古い PyTorch が壊れる問題として知られているので、mkl==2024.0.* に固定しました。
もうひとつは chumpy や DPVO ビルドの途中で出た ModuleNotFoundError: No module named 'pip' でした。こちらは conda 環境に pip と古めの setuptools==59.5.0 を明示的に入れることで安定しました。
最終的に通った WHAM の Dockerfile
最終的にビルドが通った Dockerfile は次のような内容です。
FROM nvidia/cuda:11.3.1-cudnn8-devel-ubuntu20.04
# Install prerequisites
RUN apt-get update && \
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
wget git unzip build-essential curl ninja-build libglib2.0-0 libsm6 libxrender-dev libxext6 libgl1-mesa-glx && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
WORKDIR /workspace
# Clone the WHAM repo
RUN git clone https://github.com/yohanshin/WHAM.git --recursive
WORKDIR /workspace/WHAM
# Install Miniforge (based on conda-forge)
RUN curl -L -o /tmp/miniforge.sh \
https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh && \
bash /tmp/miniforge.sh -b -p /opt/conda && \
rm /tmp/miniforge.sh
ENV PATH=/opt/conda/bin:$PATH
# channels are limited to conda-forge
RUN conda config --remove-key channels || true && \
conda config --add channels conda-forge && \
conda config --set channel_priority strict
# Create Conda environment
RUN conda create -y -n wham python=3.9 && \
conda clean -afy
ENV CONDA_DEFAULT_ENV=wham
ENV PATH=/opt/conda/envs/wham/bin:$PATH
# Install PyTorch libraries
RUN conda install -y -n wham \
pytorch==1.11.0 torchvision==0.12.0 torchaudio==0.11.0 mkl==2024.0.* cudatoolkit=11.3 -c pytorch && \
conda clean -afy
# pip / setuptools pin for legacy packages
RUN conda install -y -n wham setuptools==59.5.0 pip -c conda-forge && \
conda clean -afy
# Install WHAM dependencies
RUN pip install -r requirements.txt
# Install ViTPose
RUN pip install -v -e third-party/ViTPose
# Install DPVO with Eigen
ENV TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6"
RUN cd third-party/DPVO && \
wget https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.zip && \
unzip eigen-3.4.0.zip -d thirdparty && rm -f eigen-3.4.0.zip && \
conda install -y -n wham pytorch-scatter=2.0.9 -c rusty1s && \
conda clean -afy && \
conda install -y -n wham gxx=9.5 -c conda-forge && \
conda clean -afy && \
pip install .
CMD ["/bin/bash"]
この構成の重要な点は、ホストに CUDA 12.x が入っていても、コンテナ内では PyTorch 1.11.0 と CUDA 11.3 系 toolkit / headers / build tools が一貫して見えることです。
Pixi と Docker の役割分担
今回やってみて、Pixi と Docker は競合というより 役割分担 で考えるのがよさそうだと感じました。
-
Pixi: Python 依存の切り分け、
mmcvや ViTPose の導入確認、WHAM 本体コードの読解や軽い検証に向いている。 - Docker: DPVO を含むフル構成の再現、CUDA 拡張ビルド、本番に近い実行確認に向いている。
この整理にすると、Pixi で得た知見も無駄にならず、Docker 成功版にも自然につながります。
まとめ
今回の検証で一番大きかったのは、WHAM の環境構築で起きる問題が「単に依存が多い」というより、古い PyTorch / CUDA 前提と、現在の Linux / パッケージ環境とのズレに起因していると整理できたことでした。
Pixi 版では、PyTorch3D や mmcv==1.3.9、ViTPose まではかなり進められた一方、DPVO の CUDA 拡張ビルドでは system CUDA 12.x との不整合や cuda_runtime.h 不足にぶつかり、CUDA 11.3 世代の build toolchain を仮想環境だけで完結させる難しさが見えました。
一方 Docker 版では、nvidia/cuda:11.3.1-cudnn8-devel-ubuntu20.04 をベースにすることで、CUDA 11.3 系の runtime・headers・build tools をまとめて閉じ込められました。さらに mkl==2024.0.* 固定、pip と setuptools==59.5.0 の明示導入、TORCH_CUDA_ARCH_LIST の設定といった調整を加えることで、最終的に WHAM + ViTPose + DPVO の構成を通すことができました。
実務的な結論としては、普段のコード読解や軽い依存確認には Pixi、フル構成の再現と実行には Docker という役割分担が最も現実的でした。WHAM のように「少し古い研究コードを現在の GPU 環境で動かす」ケースでは、単にパッケージを入れ直すだけでなく、どこまでを仮想環境で吸収し、どこからをコンテナに閉じ込めるかを切り分けることが大事だと感じました。