Z-Image

How to Install and Use Z-Image on Local PC in ComfyUI: Complete 2025 Guide

Dec 31, 2025

How to Install and Use Z-Image on Local PC in ComfyUI: Complete 2025 Guide

Introduction

Z-Image is a powerful 6-billion parameter AI image generation model developed by Alibaba's Tongyi MAI team. Released under the Apache 2.0 license, it offers fast, high-quality image generation that runs efficiently on consumer hardware. This comprehensive guide walks you through installing and using Z-Image locally with ComfyUI, from system requirements to generating your first images.

10

What is Z-Image?

Z-Image is an open-source diffusion model designed for text-to-image generation. The model comes in several variants:

  • Z-Image Turbo: Optimized for speed with 8-step generation
  • Z-Image Base: Standard version for balanced quality and speed
  • Z-Image Edit: Specialized for image editing tasks

Key advantages include:

  • Low VRAM requirements: Runs on GPUs with 6-12 GB VRAM
  • Fast generation: 8-step sampling produces results in seconds
  • Open license: Apache 2.0 allows commercial use without restrictions
  • ComfyUI integration: Native support for node-based workflows

System Requirements

Before installing Z-Image, verify your system meets these requirements:

Minimum Hardware

  • GPU: NVIDIA GPU with 6 GB VRAM (8 GB recommended)
  • RAM: 16 GB system memory
  • Storage: 15 GB free disk space for models
  • OS: Windows 10/11, Linux, or macOS

Software Prerequisites

  • Python: Version 3.10 or 3.11 (3.12 not yet fully supported)
  • Git: For cloning repositories
  • CUDA: Version 11.8 or 12.1 for NVIDIA GPUs
  • GPU: NVIDIA RTX 3060 (12 GB) or higher
  • RAM: 32 GB for optimal performance
  • Storage: SSD for faster model loading

Step 1: Install ComfyUI

ComfyUI is a node-based interface for running diffusion models. Follow these steps for installation:

Windows Installation

  1. Clone the ComfyUI repository:
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
  1. Create a virtual environment:
python -m venv venv
venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Install PyTorch with CUDA support:
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu121

Linux Installation

  1. Clone and navigate to ComfyUI:
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
  1. Create virtual environment:
python3 -m venv venv
source venv/bin/activate
  1. Install dependencies:
pip install -r requirements.txt
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu121

Verify Installation

Launch ComfyUI to confirm successful installation:

python main.py

Access the interface at http://localhost:8188 in your web browser.

Step 2: Download Z-Image Models

Z-Image requires three model files. Download them from Hugging Face and place them in the correct ComfyUI directories.

Required Model Files

File Name Size Download Link Destination Folder
z_image_turbo_bf16.safetensors ~12 GB Download ComfyUI/models/diffusion_models/
qwen_3_4b.safetensors ~8 GB Download ComfyUI/models/text_encoders/
ae.safetensors ~300 MB Download ComfyUI/models/vae/

Download Methods

Method 1: Manual Download

  1. Visit each Hugging Face link
  2. Click "Download" button
  3. Move files to corresponding folders

Method 2: Using Hugging Face CLI (Recommended)

# Install Hugging Face CLI
pip install huggingface-hub

# Download all models at once
huggingface-cli download Comfy-Org/z_image_turbo --local-dir ./models/z-image-turbo --include "split_files/*"

Verify Folder Structure

Confirm your directory structure matches this layout:

ComfyUI/
└── models/
    ├── diffusion_models/
    │   └── z_image_turbo_bf16.safetensors
    ├── text_encoders/
    │   └── qwen_3_4b.safetensors
    └── vae/
        └── ae.safetensors

Step 3: Update ComfyUI

Ensure ComfyUI is up-to-date for full Z-Image compatibility:

Windows:

cd ComfyUI
git pull origin master
pip install -r requirements.txt

Linux/macOS:

cd ComfyUI
git pull origin master
pip install -r requirements.txt

Restart ComfyUI after updating:

python main.py

Step 4: Load Z-Image Workflow

ComfyUI uses JSON workflow files to define node configurations. Download a pre-configured Z-Image workflow to get started quickly.

Download Workflow File

  1. Download the Z-Image Turbo workflow: Z-Image-Turbo-BF16-T2I.json
  2. Save the file to your computer

Load Workflow in ComfyUI

  1. Open ComfyUI in your browser (http://localhost:8188)
  2. Drag and drop the JSON file onto the ComfyUI canvas
  3. The workflow will automatically populate with all required nodes

The workflow includes:

  • Text Encoder Node: Processes your text prompt
  • Diffusion Model Node: Generates the image
  • VAE Decoder Node: Converts latent space to visible image
  • Sampler Node: Controls generation steps and quality

Step 5: Configure Generation Settings

Before generating images, configure these key parameters:

Basic Settings

Prompt: Enter your image description

  • Be specific about subject, style, lighting, and composition
  • Example: "A serene mountain landscape at sunset, photorealistic, 8K quality"

Steps: Set to 8 for Z-Image Turbo

  • Turbo model is optimized for 8-step generation
  • Higher steps don't significantly improve quality

Image Dimensions: Choose resolution

  • Standard: 1024 × 1024 (square)
  • Landscape: 1280 × 720 (16:9)
  • Portrait: 720 × 1280 (9:16)

Advanced Settings

CFG Scale: Controls prompt adherence (recommended: 3.5-7.0)

  • Lower values: More creative, less literal
  • Higher values: Stricter prompt following

Seed: Controls randomness

  • Use -1 for random results
  • Use specific number to reproduce images

Sampler: Choose sampling method

  • Recommended: Euler or DPM++ 2M

Step 6: Generate Your First Image

Follow these steps to create your first Z-Image:

  1. Enter your prompt in the text input node
  2. Verify model selection:
    • Diffusion Model: z_image_turbo_bf16.safetensors
    • Text Encoder: qwen_3_4b.safetensors
    • VAE: ae.safetensors
  3. Set image dimensions (e.g., 1024 × 1024)
  4. Click "Queue Prompt" button
  5. Wait for generation (typically 5-15 seconds)
  6. View result in the output node

Example Prompts

Photorealistic Portrait:

Professional headshot of a business executive, studio lighting,
sharp focus, neutral background, 8K quality

Fantasy Scene:

Ancient dragon perched on mountain peak, dramatic sunset,
volumetric clouds, epic fantasy art style

Architectural Visualization:

Modern minimalist house, glass walls, surrounded by forest,
golden hour lighting, architectural photography

Troubleshooting Common Issues

Out of Memory Errors

Problem: GPU runs out of VRAM during generation

Solutions:

  1. Reduce image resolution (try 768 × 768)
  2. Close other GPU-intensive applications
  3. Enable --lowvram flag when launching ComfyUI:
    python main.py --lowvram

Model Not Found

Problem: ComfyUI can't locate model files

Solutions:

  1. Verify files are in correct folders
  2. Check file names match exactly (case-sensitive)
  3. Refresh ComfyUI browser page (Ctrl+R)
  4. Restart ComfyUI server

Slow Generation Speed

Problem: Image generation takes too long

Solutions:

  1. Verify CUDA is properly installed
  2. Check GPU is being used (not CPU):
    nvidia-smi
  3. Update GPU drivers to latest version
  4. Reduce image resolution temporarily

Black or Corrupted Images

Problem: Generated images appear black or distorted

Solutions:

  1. Verify VAE model is loaded correctly
  2. Try different CFG scale values (3.5-7.0)
  3. Check prompt doesn't contain conflicting instructions
  4. Regenerate with different seed value

Performance Optimization Tips

Speed Improvements

  1. Use SSD storage: Store models on SSD for faster loading
  2. Enable xFormers: Install for memory-efficient attention
    pip install xformers
  3. Batch generation: Generate multiple images simultaneously
  4. Reduce precision: Use bf16 models (already default for Z-Image Turbo)

Quality Enhancements

  1. Increase resolution: Use 1280 × 1280 or higher for detailed images
  2. Refine prompts: Add quality keywords like "8K", "highly detailed", "professional"
  3. Adjust CFG scale: Fine-tune between 5.0-7.0 for optimal results
  4. Use negative prompts: Specify what to avoid in generation

Advanced Usage

Image-to-Image Generation

Z-Image supports using reference images as starting points:

  1. Add "Load Image" node to workflow
  2. Connect to diffusion model input
  3. Set denoising strength (0.3-0.8)
  4. Generate variations of existing images

ControlNet Integration

For precise control over composition:

  1. Install ControlNet custom nodes
  2. Download ControlNet models
  3. Use edge detection, pose, or depth maps
  4. Guide generation with structural references

Batch Processing

Generate multiple images efficiently:

  1. Set batch size in workflow (2-4 images)
  2. Use different seeds for variation
  3. Process multiple prompts sequentially
  4. Save outputs automatically

Conclusion

You now have Z-Image running locally on your PC with ComfyUI. This setup provides:

  • Full control: No cloud dependencies or usage limits
  • Privacy: All generation happens on your hardware
  • Customization: Modify workflows for specific needs
  • Cost-effective: No per-image generation fees

Next Steps

  1. Experiment with prompts: Test different styles and subjects
  2. Explore workflows: Download community-created workflows
  3. Install custom nodes: Extend ComfyUI functionality
  4. Join communities: Share results and learn techniques

Additional Resources

Start creating stunning AI-generated images today with Z-Image and ComfyUI on your local PC.

Zimage.run Team

How to Install and Use Z-Image on Local PC in ComfyUI: Complete 2025 Guide | Blog