ZImage 환경 구축 가이드 (PyTorch 2.6.0 + CUDA 12.4 기준)

본 문서는 Windows 환경에서 ZImage 실행을 위한 Python 및 라이브러리 설치 절차를 정리한 기술 문서이다.
실제 동작이 확인된 조합을 기준으로 구성하였다.

---

1. Python 설정

Python 임베디드 환경을 사용할 경우, python310._pth 파일을 수정해야 한다.

파일을 열고 아래 항목의 주석을 제거한다.

#import site

다음과 같이 변경한다.

import site

이 설정이 활성화되지 않으면 pip 및 외부 패키지 사용이 제한된다.

---

2. pip 설치 및 기본 환경 구성

pip이 없는 경우 아래 명령으로 설치한다.

curl -O https://bootstrap.pypa.io/get-pip.py

D:\Flux2\python\python.exe get-pip.py
D:\Flux2\python\python.exe -m pip install --upgrade pip

이후 numpy 버전을 제한하여 설치한다.

D:\Flux2\python\python.exe -m pip install "numpy<2"

numpy 2.x는 일부 라이브러리와 호환 문제가 발생할 수 있다.

---

3. PyTorch 설치

ZImage 환경에서 동작이 확인된 PyTorch 버전은 다음과 같다.

D:\Flux2\python\python.exe -m pip install torch==2.6.0+cu124 torchvision==0.21.0+cu124 torchaudio==2.6.0+cu124 --index-url https://download.pytorch.org/whl/cu124

CUDA 12.4 기반이며, GPU 가속을 사용한다.

---

4. PyTorch 동작 확인

설치 후 아래 명령으로 정상 동작 여부를 확인한다.

D:\Flux2\python\python.exe -c "import torch; print(torch.__version__)"

추가로 CUDA 및 GPU 인식 여부를 확인한다.

D:\Flux2\python\python.exe -c "import torch; print('Torch:', torch.__version__); print('CUDA 사용 가능:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0))"

정상적인 경우 CUDA 사용 가능 상태와 GPU 이름이 출력된다.

---

5. diffusers 설치

ZImage 환경에서는 특정 버전의 diffusers를 사용한다.

D:\Flux2\python\python.exe -m pip install diffusers==0.33.1

Git 최신 버전은 API 변경으로 인해 호환 문제가 발생할 수 있다.

---

6. 필수 라이브러리 설치

기본 실행에 필요한 라이브러리를 설치한다.

D:\Flux2\python\python.exe -m pip install transformers accelerate safetensors pillow huggingface_hub
D:\Flux2\python\python.exe -m pip install peft

---

7. 추가 패키지 설치

환경에 따라 필요한 추가 패키지를 설치한다.

D:\Flux2\python\python.exe -m pip install gguf>=0.10.0

LyCORIS 사용 시 다음을 추가한다.

D:\Flux2\python\python.exe -m pip install git+https://github.com/KohakuBlueleaf/LyCORIS.git

---

8. 최종 확인

전체 설치가 완료되면 아래 명령으로 주요 패키지 버전을 확인한다.

D:\Flux2\python\python.exe -c "import torch; import diffusers; print(torch.__version__); print(diffusers.__version__)"

---

9. 실행

ZImage 스크립트를 실행한다.

D:\Flux2\python\python.exe D:\Flux2\zimage.py

---

환경 요약

• Python: 3.10 (임베디드)
• PyTorch: 2.6.0 + cu124
• CUDA: 정상 활성화
• GPU: RTX 3060 기준 동작 확인
• diffusers: 0.33.1
• numpy: 2 미만

해당 구성은 ZImage 실행 기준으로 검증된 환경이다.