---
title: Zig
emoji: 🏃
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false
---


# Z-Image Hugging Face Space

Gradio Space using the official Z-Image pipeline (`Tongyi-MAI/Z-Image-Turbo`) with optional LoRA injection (Civitai link you provided). There is **no SD1.5 fallback**—if the Z-Image model is unavailable, the Space will fail to load.

## Files
- `app.py`: Z-Image pipeline, FlowMatch scheduler, LoRA toggle/strength, simple gallery UI.
- `requirements.txt`: Python deps for Spaces/local runs.
- `lora/`: Place `zit-mystic-xxx.safetensors` here (or point `LORA_PATH` to your filename).
- `.gitattributes`: Tracks `.safetensors` via Git LFS for large LoRA files.

## Using on Hugging Face Spaces
1) Create a Space (Python) and select a GPU hardware type.  
2) Add/clone this repo into the Space.  
3) Manually add the LoRA file from https://civitai.com/models/2206377/zit-mystic-xxx to `lora/zit-mystic-xxx.safetensors` (or set `LORA_PATH`). Network fetch of Civitai is not handled in the Space.  
4) If model download fails with a token error, set `HF_TOKEN` in the Space secrets (some repos require authentication).  
5) (Optional) Toggle advanced envs below; then the Space will launch `app.py`. The header shows whether the LoRA was detected/loaded.
   - If the header/log says `PEFT backend is required for LoRA`, install `peft` (already included in `requirements.txt`) and restart/rebuild.

## Environment variables
- `MODEL_PATH` (default `Tongyi-MAI/Z-Image-Turbo`): HF repo or local path for the Z-Image model.
- `LORA_PATH` (default `lora/zit-mystic-xxx.safetensors`): Path to the LoRA file; loaded if present.
- `HF_TOKEN`: HF token for gated/private models or faster pulls.
- `MODEL_DTYPE` (default `auto`): `bf16` if supported, else `fp16` (override with `bf16`/`fp16`/`fp32`).
- `ENABLE_COMPILE` (default `true`): Enable `torch.compile` on the transformer.
- `ENABLE_WARMUP` (default `false`): Run a quick warmup across resolutions after load (adds startup time).
- `ATTENTION_BACKEND` (default `flash_3`): Backend for transformer attention (falls back to `flash`/`xformers`/`native`).
- `OFFLOAD_TO_CPU_AFTER_RUN` (default `false`): Move the model back to CPU after each generation (useful on ZeroGPU; slower on normal GPUs).
- `ENABLE_AOTI` (default `true`): Try to load ZeroGPU AoTI blocks via `spaces.aoti_blocks_load` for faster inference.
- `AOTI_REPO` (default `zerogpu-aoti/Z-Image`): AoTI blocks repo.
- `AOTI_VARIANT` (default `fa3`): AoTI variant.
- `AOTI_ALLOW_LORA` (default `false`): Allow AoTI to load even if LoRA adapters are loaded (may crash; AoTI blocks generally don’t support LoRA).
- `DEBUG` (default `false`): When set to a truthy value (`1`, `true`, `yes`, `on`), hide the Status/Debug floating panel.

## Run locally
```bash
python -m venv .venv
.venv\Scripts\activate  # Windows; on Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python app.py
```
Place the LoRA file under `lora/` first (or set `LORA_PATH`); otherwise the app will run the base Z-Image model without LoRA.

## UI controls
- Prompt
- Resolution category + explicit WxH selection
- Seed (with random toggle)
- Steps + Time Shift
- Advanced: CFG, scheduler + extra scheduler params, max sequence length
- LoRA toggle + strength (enabled only if the file is found)

## Git LFS note
`.gitattributes` tracks `.safetensors` with LFS. If you commit the LoRA, run `git lfs install` once before pushing so large files go through LFS.