CLI and core features

• Z-Image-Turbo Model: Utilizes the high-quality Tongyi-MAI/Z-Image-Turbo model and quatized variants via diffusers.
• MPS Acceleration: Optimized for Mac users with Apple Silicon.
• ROCm Support: Explicitly supported on Linux for AMD GPUs.
• Intel XPU Support: Supports Intel XPU when running an Intel-enabled PyTorch build.
• Attention Slicing Auto-detection: Automatically manages memory usage (e.g., enables attention slicing for systems with lower RAM/VRAM) to prevent Out-of-Memory errors and optimize performance.
• Seed Control: Reproducible image generation via CLI or Web UI.
• Multiple LoRA Support: Upload/manage LoRAs in the web UI, apply up to 4 with per-LoRA strengths in a single generation; CLI supports multiple --lora entries with optional strengths.
• Automatic Dimension Adjustment: Ensures image dimensions are compatible (multiples of 16).
• Customizable Output Directory: Image output directory can be customized via config file and environment variable.

Web UI features

• Multilanguage Support: English, Japanese, Chinese Simplified (zh-CN), and Chinese Traditional (zh-TW) are supported.
• History Browser: Efficiently search and browse your past generations with a paginated history that loads more items as you scroll.
• Hardware-aware Model Recommendation: The Web UI dynamically presents model precision options based on your system's detected RAM/VRAM, recommending the optimal choice for your hardware. You can also inspect available models and recommendations via the CLI.
• Image Sharing: The generated image can be downloaded to browser download directory, conveniently shared via OS share protocol, and copied into clipboard.
• Theme Switch: Light, dark and auto themes.
• Mobile compatible: Responsive layout for mobile devices.

MCP features

• MCP Server (stdio + SSE + Streamable HTTP): Expose tools for image generation, listing models, and viewing history over Model Context Protocol; stdio entrypoints (zimg mcp, zimg-mcp) for local agents, SSE available at /mcp-sse, and MCP 2025-03-26 Streamable HTTP transport at /mcp.
• Transport-Agnostic Content: All transports (stdio, SSE, Streamable HTTP) return identical structured content for consistent agent integration.
• Client Transport Selection: Clients should try Streamable HTTP (/mcp) first for optimal performance, falling back to SSE (/mcp-sse) if needed.

Requirements

• Python >= 3.11
• uv (recommended for dependency management)

Python 3.12+ Note: torch.compile is disabled by default for Python 3.12+ due to known compatibility issues with the Z-Image model architecture. If you want to experiment with torch.compile on Python 3.12+, set ZIMAGE_ENABLE_TORCH_COMPILE=1 via environment variable or in ~/.z-image-studio/config.json (experimental, may cause errors).

GPU acceleration notes

• NVIDIA (CUDA): Works with standard PyTorch CUDA builds.
• AMD on Linux (ROCm): Explicitly supported on Linux.

  Note: AMD GPU support currently requires ROCm, which is only available for Linux PyTorch builds. Windows users with AMD GPUs will currently fall back to CPU.

  • Installation: Install AMD ROCm drivers/runtime for your distribution. Then install PyTorch with ROCm support (e.g., via pip install torch --index-url https://download.pytorch.org/whl/rocm6.1 or similar). Ensure the PyTorch ROCm version matches your installed driver version.
  • Verification: The app will automatically detect your device as "rocm". You can confirm this by running zimg models.
  • Troubleshooting:
    • If the app falls back to CPU, ensure torch.version.hip is detected.
    • HSA Override: For some consumer GPUs (e.g., RX 6000/7000 series) not officially supported by all ROCm versions, you may need to set HSA_OVERRIDE_GFX_VERSION (e.g., 10.3.0 for RDNA2, 11.0.0 for RDNA3).
    • Performance: torch.compile is disabled by default on ROCm due to experimental support. You can force-enable it with ZIMAGE_ENABLE_TORCH_COMPILE=1 if your setup (Triton/ROCm version) supports it.
• Intel (XPU): Supported when PyTorch is built with Intel XPU backend.
  • Verification: The app will detect your device as "xpu" in zimg models.
  • Compatibility: CUDA-specific components/features are not guaranteed on XPU.
• Apple Silicon (MPS): Uses PyTorch MPS backend on macOS.

Global installation

If you just want the zimg CLI to be available from anywhere, install it as a uv tool:

uv tool install git+https://github.com/iconben/z-image-studio.git
# or, if you have the repo cloned locally:
# git clone https://github.com/iconben/z-image-studio.git
# cd z-image-studio
# uv tool install .

After this, the zimg command is available globally:

zimg --help

To update z-image-studio:

uv tool upgrade z-image-studio
# or, if you have the repo cloned locally, you pull the latest source code:
# git pull

Windows Installation

For Windows users, a pre-built installer is available that bundles everything you need:

1. Download the latest installer from GitHub Releases
2. Run Z-Image-Studio-Windows-x64-x.x.x.exe
3. Follow the installation wizard
4. Launch from the Start Menu:
   • Z-Image Studio (Web UI): Starts the web server and opens your browser
   • Z-Image Studio CLI: Opens a console for command-line usage

Installation Details

• Install Location: C:\Program Files\Z-Image Studio
• User Data: %LOCALAPPDATA%\z-image-studio (contains database, LoRAs, and outputs)
• Uninstall: Use "Add or Remove Programs" or the uninstall shortcut in the Start Menu

System Requirements

• Windows 10 or Windows 11
• NVIDIA GPU with CUDA support (recommended) or compatible AMD GPU
• 8GB+ RAM (16GB+ recommended for full precision models)

Docker Installation

Run Z-Image Studio in a container with Docker:

Quick Start

# Create persistent volume
docker volume create zimg-data

# Run the container
docker run -d \
  --name z-image-studio \
  -p 8000:8000 \
  -v zimg-data:/data \
  -v zimg-config:/home/appuser/.z-image-studio \
  -v zimg-outputs:/data/outputs \
  iconben/z-image-studio:latest

Then open http://localhost:8000 in your browser.

With Docker Compose

Create a docker-compose.yml file:

services:
  z-image-studio:
    image: iconben/z-image-studio:latest
    container_name: z-image-studio
    ports:
      - "8000:8000"
    volumes:
      - zimg-data:/data
      - zimg-config:/home/appuser/.z-image-studio
      - zimg-outputs:/data/outputs
    restart: unless-stopped

volumes:
  zimg-data:
  zimg-config:
  zimg-outputs:

Then run:

docker compose up -d

With GPU Support

NVIDIA GPU:

services:
  z-image-studio:
    image: iconben/z-image-studio:latest
    container_name: z-image-studio
    ports:
      - "8000:8000"
    volumes:
      - zimg-data:/data
      - zimg-config:/home/appuser/.z-image-studio
      - zimg-outputs:/data/outputs
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

volumes:
  zimg-data:
  zimg-config:
  zimg-outputs:

AMD GPU (Linux):

services:
  z-image-studio:
    image: iconben/z-image-studio:latest
    container_name: z-image-studio
    ports:
      - "8000:8000"
    volumes:
      - zimg-data:/data
      - zimg-config:/home/appuser/.z-image-studio
      - zimg-outputs:/data/outputs
    devices:
      - /dev/dri:/dev/dri
    restart: unless-stopped

volumes:
  zimg-data:
  zimg-config:
  zimg-outputs:

Then run:

docker compose up -d

With Docker Run

Basic:

docker run -d \
  --name z-image-studio \
  -p 8000:8000 \
  -v zimg-data:/data \
  -v zimg-config:/home/appuser/.z-image-studio \
  -v zimg-outputs:/data/outputs \
  iconben/z-image-studio:latest

NVIDIA GPU:

docker run -d \
  --n