Installation Guide

Comprehensive installation instructions for Hanzo Studio.

System Requirements

Hardware

Minimum:

8GB RAM
10GB free disk space

GPU (Recommended):

NVIDIA GPU with 8GB+ VRAM (CUDA support)
OR Apple Silicon (M1/M2/M3/M4) with MLX

CPU-Only (Slower):

Multi-core CPU (4+ cores recommended)
16GB+ RAM

Software

Python 3.8+
Git
wget
CUDA Toolkit 11.8+ (for NVIDIA GPUs)

Installation Methods

Method 1: Automated Setup (Recommended)

git clone https://github.com/hanzoai/painter.git
cd painter
make all

Method 2: Manual Installation

Step 1: Clone Repository

git clone https://github.com/hanzoai/painter.git
cd painter

Step 2: Install Hanzo Studio

git clone https://github.com/comfyanonymous/Hanzo Studio.git
cd Hanzo Studio
pip install -r requirements.txt

Step 3: Install Hanzo Custom Nodes

cd custom_nodes

# Hanzo-DiffuEraser
git clone https://github.com/hanzoai/Hanzo-DiffuEraser.git

# Hanzo-VideoHelper
git clone https://github.com/hanzoai/Hanzo-VideoHelper.git
cd Hanzo-VideoHelper && pip install -r requirements.txt && cd ..

# Hanzo-EasyUse
git clone https://github.com/hanzoai/Hanzo-EasyUse.git

# Hanzo-KJNodes
git clone https://github.com/hanzoai/Hanzo-KJNodes.git
cd Hanzo-KJNodes && pip install -r requirements.txt && cd ..

# Hanzo-LayerStyle
git clone https://github.com/hanzoai/Hanzo-LayerStyle.git

cd ../..

Step 4: Download Models

# SAM2 models (automated)
make download-models

# OR manually:
mkdir -p Hanzo Studio/models/sam2
wget -O Hanzo Studio/models/sam2/sam2_hiera_large.pt \
  https://dl.fbaipublicfiles.com/segment_anything_2/072824/sam2_hiera_large.pt
wget -O Hanzo Studio/models/sam2/sam2_hiera_base_plus.pt \
  https://dl.fbaipublicfiles.com/segment_anything_2/072824/sam2_hiera_base_plus.pt

Required Manual Downloads:

Realistic Vision V5.1
- Download: realisticVisionV51_v51VAE.safetensors
- Place in: Hanzo Studio/models/checkpoints/
PCM DiffuEraser Model
- Download: pcm_sd15_smallcfg_2step_converted.safetensors
- Place in: Hanzo Studio/models/diffusers/

Step 5: Install Workflow

mkdir -p Hanzo Studio/workflows
cp inpainting-workflow.json Hanzo Studio/workflows/

Method 3: Docker (Coming Soon)

docker compose up

Optional Components

SAM2 (Advanced Segmentation)

For precise object segmentation:

make install-sam2

MLX (Apple Silicon Acceleration)

For M1/M2/M3/M4 Macs:

make install-mlx

Benefits:

70% faster model loading
35% faster inference
30% lower memory usage

Note: Currently optimized for Flux models. SD 1.5 support coming soon.

Verification

Test Installation

make test

Expected output:

PyTorch: 2.x.x
CUDA available: True (or False for CPU/MLX)
CUDA version: 11.8+ (if GPU)

Check Installed Components

make info

Verify Models

make models-info

Should show:

SAM2 models (2 files)
Checkpoint models
Diffuser models

Platform-Specific Notes

Windows

Install in WSL2 for best compatibility:

# In WSL2
sudo apt-get update
sudo apt-get install python3-pip git wget
make all

macOS

Install Homebrew dependencies:

brew install python@3.11 git wget
make all

For Apple Silicon, install MLX:

make install-mlx

Linux

Install dependencies:

# Ubuntu/Debian
sudo apt-get install python3-pip git wget

# Fedora/RHEL
sudo dnf install python3-pip git wget

# Arch
sudo pacman -S python-pip git wget

For NVIDIA GPUs, install CUDA toolkit:

# Follow NVIDIA's official guide
# https://developer.nvidia.com/cuda-downloads

Troubleshooting Installation

Common Issues

“Python not found”

# Install Python 3.8+
# macOS
brew install python@3.11

# Ubuntu
sudo apt-get install python3.11

# Windows
# Download from python.org

“Git not found”

# macOS
brew install git

# Ubuntu
sudo apt-get install git

# Windows
# Download from git-scm.com

“CUDA out of memory”

Use make run-lowvram
Reduce video_length parameter
Close other GPU-intensive applications

“Module not found”

# Reinstall dependencies
cd Hanzo Studio
pip install -r requirements.txt --force-reinstall

“Models not found”

# Verify model paths
make models-info

# Re-download if needed
make download-models

Updating

Keep Hanzo Studio up to date:

# Update all components
make update

# This updates:
# - Hanzo Studio core
# - All custom nodes
# - Git pulls latest changes

Uninstalling

Remove Hanzo Studio:

make uninstall

Warning: This removes the entire Hanzo Studio directory including downloaded models.

← Quick Start

Usage Guide →

🎨 Hanzo Painter