ComfyUI + ComfyUI-3D-Pack 트러블슈팅 기록

이 문서는 설치/운영 전체 과정을 적는 문서가 아니라, 실제로 발생한 오류와 그 오류를 해결하기 위해 적용한 수정사항만 기록한다.

상태 표기: 해결 / 진행 중

1. uv 가상환경 충돌 및 Python 3.14 호환성 문제 — 해결

증상

별도 가상환경과 프로젝트 .venv가 동시에 존재하면서 다음과 같은 경고가 발생했다.

VIRTUAL_ENV=... does not match the project environment path `.venv`

또 초기 프로젝트가 Python 3.14 기준으로 잡혀 3D-Pack 의존성과 호환 문제가 발생했다.

수정

가상환경을 프로젝트 .venv 하나로 통일하고 Python 3.12로 고정했다.

uv python install 3.12
uv venv --python 3.12
uv python pin 3.12

pyproject.toml:

requires-python = ">=3.12,<3.13"

2. 3D-Pack `utils3d` requirements 파싱 오류 — 해결

증상

InvalidRequirement:
git+https://github.com/EasternJournalist/utils3d.git#egg=utils3d

원인

3D-Pack requirements의 오래된 #egg= Git 의존성 표기를 새 setuptools/uv가 정상 파싱하지 못했다.

수정

utils3d를 직접 uv 의존성으로 등록했다.

uv add "utils3d @ git+https://github.com/EasternJournalist/utils3d.git"

기존 requirements에서 해당 줄을 제외한 뒤 나머지를 설치했다.

grep -v "EasternJournalist/utils3d" \
  comfy-src/custom_nodes/ComfyUI-3D-Pack/requirements.txt \
  > /tmp/comfy3d_requirements.txt

uv add -r /tmp/comfy3d_requirements.txt

3. 3D-Pack 설치 중 `No module named pip` — 해결

증상

No module named pip

원인

uv가 만든 .venv에는 pip가 없었는데, 3D-Pack 설치 스크립트가 내부적으로 python -m pip를 호출했다.

수정

uv pip install --python .venv/bin/python pip

4. PyTorch CUDA 인덱스 때문에 일반 패키지 해석 실패 — 해결

증상

예시:

Because only cmake==3.25.0 is available
and your project depends on cmake>=4.4.4

원인

PyTorch CUDA 전용 인덱스가 프로젝트 전체 패키지의 기본 검색 경로처럼 적용되어 cmake 같은 일반 패키지까지 PyTorch 저장소에서 찾으려 했다.

수정

PyTorch 인덱스를 explicit = true로 설정하고 torch 계열만 해당 인덱스를 사용하도록 제한했다.

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch-cu128" }
torchvision = { index = "pytorch-cu128" }
torchaudio = { index = "pytorch-cu128" }

5. PyTorch import 시 `libnccl.so.2` 누락 — 해결

증상

ImportError: libnccl.so.2: cannot open shared object file

원인

nvidia-nccl-cu12 패키지 메타데이터는 있었지만 실제 NCCL 라이브러리 파일이 정상 설치되지 않았다.

수정

.venv/bin/python -m pip uninstall -y nvidia-nccl-cu12

.venv/bin/python -m pip install \
  --no-cache-dir \
  --force-reinstall \
  --index-url https://pypi.org/simple \
  nvidia-nccl-cu12==2.26.2

확인 파일:

.venv/lib/python3.12/site-packages/nvidia/nccl/lib/libnccl.so.2

수정 후 확인:

PyTorch: 2.7.0+cu128
CUDA: 12.8
GPU available: True

6. NumPy 2.x에서 `np.Inf` 제거로 gpytoolbox import 실패 — 해결

증상

AttributeError: `np.Inf` was removed in the NumPy 2.0 release.

실제 발생 파일:

.venv/lib/python3.12/site-packages/gpytoolbox/reach_for_the_arcs.py

원인

gpytoolbox 코드가 NumPy 2.x에서 제거된 np.Inf를 사용했다.

수정

NumPy를 내리면 최신 OpenCV와 충돌했기 때문에 문제 코드만 수정했다.

sed -i 's/np\.Inf/np.inf/g' \
  .venv/lib/python3.12/site-packages/gpytoolbox/reach_for_the_arcs.py

7. `CLIPFeatureExtractor` import 실패 — 해결

증상

ImportError: cannot import name 'CLIPFeatureExtractor' from 'transformers'

원인

설치된 Transformers 버전이 3D-Pack의 Era3D 코드가 기대하는 API와 맞지 않았다.

수정

Transformers 4.x로 고정했다.

uv add "transformers==4.57.6"

확인:

uv run python -c "from transformers import CLIPFeatureExtractor; print('OK')"

8. Unique3D / rembg provider 형식 오류 — 해결

증상

TypeError: sequence item 0: expected str instance, tuple found

발생 파일:

comfy-src/custom_nodes/ComfyUI-3D-Pack/Gen_3D_Modules/Unique3D/scripts/utils.py

원인

rembg.new_session()에 provider 옵션을 (provider, options) tuple 형태로 전달한 코드가 현재 환경과 맞지 않았다.

수정

provider를 문자열 리스트로 변경했다.

providers = [
    'CUDAExecutionProvider',
    'CPUExecutionProvider'
]

session = new_session(providers=providers)

9. `diso` 빌드 시 torch를 찾지 못함 — 해결

증상

Failed to build diso==0.1.4
ModuleNotFoundError: No module named 'torch'

원인

격리된 build 환경에서 diso가 빌드 시 필요한 torch를 볼 수 없었다.

수정

build isolation을 끄고 현재 프로젝트 환경의 torch를 사용하도록 설치했다.

uv pip install \
  --python .venv/bin/python \
  --no-build-isolation \
  diso==0.1.4

10. `diso` 빌드 시 CUDA 13.0 ↔ PyTorch CUDA 12.8 불일치 — 해결

증상

The detected CUDA version (13.0) mismatches
the version that was used to compile PyTorch (12.8).

원인

서버의 기본 nvcc는 CUDA 13.0이었지만 PyTorch는 2.7.0+cu128이었다.

수정

시스템 CUDA 13.0은 유지하고 CUDA Toolkit 12.8을 병렬 설치했다.

sudo apt install -y cuda-toolkit-12-8

현재 셸/프로세스에서는 CUDA 12.8을 명시했다.

export CUDA_HOME=/usr/local/cuda-12.8
export PATH="$CUDA_HOME/bin:$PATH"
export LD_LIBRARY_PATH="$CUDA_HOME/lib64:${LD_LIBRARY_PATH:-}"

그 뒤 diso를 다시 빌드했다.

11. Diffusers `controlnet` 모듈 경로 오류 — 해결

증상

ModuleNotFoundError: No module named 'diffusers.models.controlnet'

원인

설치된 diffusers가 3D-Pack의 Stable3DGen 코드가 기대하는 모듈 구조와 맞지 않았다.

수정

uv add "diffusers==0.30.3"

확인:

uv run python - <<'PY'
from diffusers.models.controlnet import ControlNetModel
print("controlnet import OK")
PY

12. `Load Image` 기본 MASK와 원본 이미지 크기 불일치 — 해결

증상

[Comfy3D] Resize Image Foreground 실행 시:

IndexError:
The shape of the mask [1, 64, 64] at index 1
does not match the shape of the indexed tensor
[1, 1024, 1536, 3] at index 1

원인

알파 채널이 없는 일반 이미지에서 Load Image의 MASK 출력을 그대로 사용했다.

IMAGE: 1024 x 1536
MASK : 64 x 64

수정

Load Image MASK → Invert Mask 연결을 제거하고, BiRefNet 배경 제거 노드가 생성한 실제 전경 마스크를 사용하도록 변경했다.

Load Image IMAGE
→ Remove Background
→ MASK
→ Resize Image Foreground

배경 제거 모델은 다음 위치에 배치했다.

comfy-src/models/background_removal/birefnet.safetensors

13. Stable Fast 3D Hugging Face gated repo 403 — 해결

증상

GatedRepoError: 403 Client Error
Access to model stabilityai/stable-fast-3d is restricted
and you are not in the authorized list.

원인

stabilityai/stable-fast-3d가 gated repository라서 Hugging Face 토큰이 있어도 모델 접근 승인이 없으면 다운로드할 수 없었다.

수정

.env에서 HF_TOKEN을 Jupyter 실행 프로세스에 전달.
HfApi(token=...).whoami()로 토큰 계정 확인.
동일 계정으로 Stable Fast 3D 모델 접근 권한 신청/승인.
승인 후 모델 체크포인트를 로컬에 저장.

최종 체크포인트 위치:

comfy-src/custom_nodes/ComfyUI-3D-Pack/Checkpoints/StableFast3D/model.safetensors

이후 403 오류는 통과했고 SF3D 모델 로딩 단계까지 진입했다.

14. Jupyter에서 `huggingface_hub` / `stack_data` import 오류 — 해결

증상

ModuleNotFoundError: No module named 'huggingface_hub'

오류 출력 중 추가로:

ModuleNotFoundError: No module named 'stack_data'

원인

Jupyter 커널이 Python 3.14 환경을 사용하고 있었고, 실제 ComfyUI는 Python 3.12 uv 환경을 사용하고 있었다.

Jupyter:  .../.venv/lib/python3.14/...
ComfyUI:  .../.venv/lib/python3.12/...

수정

Jupyter 커널에서 ComfyUI 패키지를 직접 import하지 않고, subprocess로 프로젝트 루트에서 uv run python을 호출하도록 변경했다.

subprocess.run(
    ["uv", "run", "python", "-c", code],
    cwd=ROOT,
    env=env,
)

이 방식으로 Hugging Face 토큰/계정 테스트를 ComfyUI와 동일한 Python 3.12 환경에서 수행했다.

15. `safetensors`의 `backend` 인자 충돌 — 진행 중

증상

[Comfy3D] Load SF3D Model 실행 시:

TypeError: torch_load_file() got an unexpected keyword argument 'backend'

발생 경로:

StableFast3D/sf3d/system.py
→ safetensors.torch.load_model(...)
→ load_file(filename, device=device, backend=backend)

확인된 Python API:

safetensors version: 0.8.0
load_file: (filename, device='cpu', *, backend='mmap')

판단

Python 레벨의 safetensors 0.8.0은 backend 인자를 지원하지만, 실제 내부 torch_load_file()은 해당 인자를 받지 못하고 있다. Python 래퍼와 네이티브 바인딩이 서로 다른 버전으로 섞였을 가능성을 의심했다.

시도한 수정

safetensors 0.8.0을 제거하고 캐시 없이 재설치했으나 동일 오류가 재현됐다.

현재 다음 수정안을 적용/검증 중이다.

.venv/bin/python -m pip uninstall -y safetensors
rm -rf .venv/lib/python3.12/site-packages/safetensors
rm -rf .venv/lib/python3.12/site-packages/safetensors-*.dist-info

.venv/bin/python -m pip install \
  --no-cache-dir \
  --force-reinstall \
  safetensors==0.7.0

현재 문서 기준으로 이 항목만 최종 해결 여부 확인 전이다.

현재 미해결 항목

[Comfy3D] Load SF3D Model
→ safetensors native binding
→ TypeError: torch_load_file() got an unexpected keyword argument 'backend'

그 외 위에 기록한 오류들은 수정 완료 상태다.

ComfyUI-3D-Pack 설치 트러블슈팅

ComfyUI + ComfyUI-3D-Pack 트러블슈팅 기록

1. uv 가상환경 충돌 및 Python 3.14 호환성 문제 — 해결

증상

수정

2. 3D-Pack utils3d requirements 파싱 오류 — 해결

증상

원인

수정

3. 3D-Pack 설치 중 No module named pip — 해결

증상

원인

수정

4. PyTorch CUDA 인덱스 때문에 일반 패키지 해석 실패 — 해결

증상

원인

수정

5. PyTorch import 시 libnccl.so.2 누락 — 해결

증상

원인

수정

6. NumPy 2.x에서 np.Inf 제거로 gpytoolbox import 실패 — 해결

증상

원인

수정

7. CLIPFeatureExtractor import 실패 — 해결

증상

원인

수정