Z-Image Studio

1# Z-Image Studio
2 
3![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)
4[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
6![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat&logo=fastapi)
7![PyTorch](https://img.shields.io/badge/PyTorch-%23EE4C2C.svg?style=flat&logo=PyTorch&logoColor=white)
8![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97-Diffusers-yellow)
9![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-MPS-gray?logo=apple)
10![Nvidia CUDA](https://img.shields.io/badge/Nvidia-CUDA-gray?logo=nvidia)
11![AMD ROCm](https://img.shields.io/badge/AMD-ROCm-gray?logo=amd)
12![Intel XPU](https://img.shields.io/badge/Intel-XPU-gray?logo=intel)
13![Docker](https://img.shields.io/badge/Docker-blue?logo=docker)
14[![Docs](https://img.shields.io/badge/docs-deepwiki.com-blue)](https://deepwiki.com/iconben/z-image-studio)
15[![AgentSeal MCP](https://agentseal.org/api/v1/mcp/https-githubcom-iconben-z-image-studio/badge)](https://agentseal.org/mcp/https-githubcom-iconben-z-image-studio)
16 
17A Cli, a webUI, and a MCP server for the **Z-Image-Turbo** text-to-image generation model (`Tongyi-MAI/Z-Image-Turbo` and its variants).
18 
19This tool is designed to run efficiently on local machines for Windows/Mac/Linux users. It features specific optimizations for **NVIDIA (CUDA)**, **AMD on Linux (ROCm)**, **Intel (XPU)**, and **Apple Silicon (MPS)**, falling back to CPU if no compatible GPU is detected.
20 
21![Screenshot 0](docs/images/screenshot0.png)
22 
23## Features
24**Hybrid Interfaces**: 
25  *   **CLI**: Fast, direct image generation from the terminal.
26  *   **Web UI**: Modern web interface for interactive generation.
27  *   **MCP Server**: Capability to be called by AI agents.
28 
29### CLI and core features
30*   **Z-Image-Turbo Model**: Utilizes the high-quality `Tongyi-MAI/Z-Image-Turbo` model and quatized variants via `diffusers`.
31*   **MPS Acceleration**: Optimized for Mac users with Apple Silicon.
32*   **ROCm Support**: Explicitly supported on Linux for AMD GPUs.
33*   **Intel XPU Support**: Supports Intel XPU when running an Intel-enabled PyTorch build.
34*   **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.
35*   **Seed Control**: Reproducible image generation via CLI or Web UI.
36*   **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.
37*   **Automatic Dimension Adjustment**: Ensures image dimensions are compatible (multiples of 16).
38*   **Customizable Output Directory**: Image output directory can be customized via config file and environment variable.
39 
40### Web UI features
41*   **Multilanguage Support**: English, Japanese, Chinese Simplified (zh-CN), and Chinese Traditional (zh-TW) are supported.
42*   **History Browser**: Efficiently search and browse your past generations with a paginated history that loads more items as you scroll.
43*   **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.
44*   **Image Sharing**: The generated image can be downloaded to browser download directory, conveniently shared via OS share protocol, and copied into clipboard. 
45*   **Theme Switch**: Light, dark and auto themes.
46*   **Mobile compatible**: Responsive layout for mobile devices.
47 
48### MCP features
49*   **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`.
50*   **Transport-Agnostic Content**: All transports (stdio, SSE, Streamable HTTP) return identical structured content for consistent agent integration.
51*   **Client Transport Selection**: Clients should try Streamable HTTP (`/mcp`) first for optimal performance, falling back to SSE (`/mcp-sse`) if needed.
52 
53## Requirements
54 
55*   Python >= 3.11
56*   `uv` (recommended for dependency management)
57 
58**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).
59 
60## GPU acceleration notes
61 
62*   **NVIDIA (CUDA)**: Works with standard PyTorch CUDA builds.
63*   **AMD on Linux (ROCm)**: Explicitly supported on Linux.
64    > **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.
65    *   **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.
66    *   **Verification**: The app will automatically detect your device as "rocm". You can confirm this by running `zimg models`.
67    *   **Troubleshooting**:
68        *   If the app falls back to CPU, ensure `torch.version.hip` is detected.
69        *   **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).
70        *   **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.
71*   **Intel (XPU)**: Supported when PyTorch is built with Intel XPU backend.
72    *   **Verification**: The app will detect your device as "xpu" in `zimg models`.
73    *   **Compatibility**: CUDA-specific components/features are not guaranteed on XPU.
74*   **Apple Silicon (MPS)**: Uses PyTorch MPS backend on macOS.
75 
76## Global installation
77 
78If you just want the `zimg` CLI to be available from anywhere, install it as a uv tool:
79 
80```bash
81uv tool install git+https://github.com/iconben/z-image-studio.git
82# or, if you have the repo cloned locally:
83# git clone https://github.com/iconben/z-image-studio.git
84# cd z-image-studio
85# uv tool install .
86```
87 
88After this, the `zimg` command is available globally:
89 
90```bash
91zimg --help
92```
93 
94To update z-image-studio:
95```bash
96uv tool upgrade z-image-studio
97# or, if you have the repo cloned locally, you pull the latest source code:
98# git pull
99```
100 
101## Windows Installation
102 
103For Windows users, a pre-built installer is available that bundles everything you need:
104 
1051. Download the latest installer from [GitHub Releases](https://github.com/iconben/z-image-studio/releases)
1062. Run `Z-Image-Studio-Windows-x64-x.x.x.exe`
1073. Follow the installation wizard
1084. Launch from the Start Menu:
109   - **Z-Image Studio (Web UI)**: Starts the web server and opens your browser
110   - **Z-Image Studio CLI**: Opens a console for command-line usage
111 
112### Installation Details
113 
114*   **Install Location**: `C:\Program Files\Z-Image Studio`
115*   **User Data**: `%LOCALAPPDATA%\z-image-studio` (contains database, LoRAs, and outputs)
116*   **Uninstall**: Use "Add or Remove Programs" or the uninstall shortcut in the Start Menu
117 
118### System Requirements
119 
120*   Windows 10 or Windows 11
121*   NVIDIA GPU with CUDA support (recommended) or compatible AMD GPU
122*   8GB+ RAM (16GB+ recommended for full precision models)
123 
124## Docker Installation
125 
126Run Z-Image Studio in a container with Docker:
127 
128### Quick Start
129 
130```bash
131# Create persistent volume
132docker volume create zimg-data
133 
134# Run the container
135docker run -d \
136  --name z-image-studio \
137  -p 8000:8000 \
138  -v zimg-data:/data \
139  -v zimg-config:/home/appuser/.z-image-studio \
140  -v zimg-outputs:/data/outputs \
141  iconben/z-image-studio:latest
142```
143 
144Then open http://localhost:8000 in your browser.
145 
146### With Docker Compose
147 
148Create a `docker-compose.yml` file:
149 
150```yaml
151services:
152  z-image-studio:
153    image: iconben/z-image-studio:latest
154    container_name: z-image-studio
155    ports:
156      - "8000:8000"
157    volumes:
158      - zimg-data:/data
159      - zimg-config:/home/appuser/.z-image-studio
160      - zimg-outputs:/data/outputs
161    restart: unless-stopped
162 
163volumes:
164  zimg-data:
165  zimg-config:
166  zimg-outputs:
167```
168 
169Then run:
170 
171```bash
172docker compose up -d
173```
174 
175#### With GPU Support
176 
177**NVIDIA GPU:**
178```yaml
179services:
180  z-image-studio:
181    image: iconben/z-image-studio:latest
182    container_name: z-image-studio
183    ports:
184      - "8000:8000"
185    volumes:
186      - zimg-data:/data
187      - zimg-config:/home/appuser/.z-image-studio
188      - zimg-outputs:/data/outputs
189    deploy:
190      resources:
191        reservations:
192          devices:
193            - driver: nvidia
194              count: all
195              capabilities: [gpu]
196    restart: unless-stopped
197 
198volumes:
199  zimg-data:
200  zimg-config:
201  zimg-outputs:
202```
203 
204**AMD GPU (Linux):**
205```yaml
206services:
207  z-image-studio:
208    image: iconben/z-image-studio:latest
209    container_name: z-image-studio
210    ports:
211      - "8000:8000"
212    volumes:
213      - zimg-data:/data
214      - zimg-config:/home/appuser/.z-image-studio
215      - zimg-outputs:/data/outputs
216    devices:
217      - /dev/dri:/dev/dri
218    restart: unless-stopped
219 
220volumes:
221  zimg-data:
222  zimg-config:
223  zimg-outputs:
224```
225 
226Then run:
227 
228```bash
229docker compose up -d
230```
231 
232### With Docker Run
233 
234**Basic:**
235```bash
236docker run -d \
237  --name z-image-studio \
238  -p 8000:8000 \
239  -v zimg-data:/data \
240  -v zimg-config:/home/appuser/.z-image-studio \
241  -v zimg-outputs:/data/outputs \
242  iconben/z-image-studio:latest
243```
244 
245**NVIDIA GPU:**
246```bash
247docker run -d \
248  --name z-image-studio \
249  -p 8000:8000 \
250  --gpus all \
251  -v zimg-data:/data \
252  -v zimg-config:/home/appuser/.z-image-studio \
253  -v zimg-outputs:/data/outputs \
254  iconben/z-image-studio:latest
255```
256 
257**AMD GPU (Linux):**
258```bash
259docker run -d \
260  --name z-image-studio \
261  -p 8000:8000 \
262  --device /dev/dri:/dev/dri \
263  -v zimg-data:/data \
264  -v zimg-config:/home/appuser/.z-image-studio \
265  -v zimg-outputs:/data/outputs \
266  iconben/z-image-studio:latest
267```
268 
269### Data Persistence
270 
271The container uses Docker volumes for persistence:
272 
273| Volume | Path | Description |
274|--------|------|-------------|
275| `zimg-data` | `/data` | Database and LoRA storage |
276| `zimg-outputs` | `/data/outputs` | Generated images |
277| `zimg-config` | `/home/appuser/.z-image-studio` | User configuration |
278 
279**Note:** The data directories (`/data` and `/data/outputs`) are set as defaults in the Dockerfile. Override with environment variables only if needed.
280 
281### Environment Variables
282 
283| Variable | Default | Description |
284|----------|---------|-------------|
285| `HOST` | `0.0.0.0` | Server bind host |
286| `PORT` | `8000` | Server bind port |
287| `ZIMAGE_BASE_URL` | Auto | Base URL for generated links |
288| `ZIMAGE_DISABLE_MCP` | `0` | Disable MCP endpoints |
289| `ZIMAGE_ENABLE_TORCH_COMPILE` | Auto | Force torch.compile |
290 
291### Development Mode
292 
293Mount source code for development:
294 
295```bash
296docker run -d \
297  --name z-image-studio-dev \
298  -p 8000:8000 \
299  -v $(pwd)/src:/app/src \
300  -v zimg-data:/data \
301  -e DEBUG=1 \
302  iconben/z-image-studio:latest
303```
304 
305### Management Commands
306 
307```bash
308# View logs
309docker logs -f z-image-studio
310 
311# Stop container
312docker stop z-image-studio
313 
314# Remove container (data preserved)
315docker rm z-image-studio
316 
317# Remove all data
318docker volume rm zimg-data zimg-outputs zimg-config
319```
320 
321## pip / uv Installation
322 
323Install Z-Image Studio via pip or uv:
324 
325```bash
326pip install z-image-studio
327# or
328uv pip install z-image-studio
329```
330 
331After installation, the `zimg` command is available globally:
332 
333```bash
334zimg --help
335```
336 
337### From Source
338 
339```bash
340git clone https://github.com/iconben/z-image-studio.git
341cd z-image-studio
342pip install -e .
343# or
344uv pip install -e .
345```
346 
347## Usage
348 
349After installation, you can use the `zimg` command directly from your terminal.
350 
351### 1. CLI Generation (Default Mode)
352Generate images directly from the command line using the `generate` (or `gen`) subcommand.
353 
354```bash
355# Basic generation
356zimg generate "A futuristic city with neon lights"
357 
358# Using the alias 'gen'
359zimg gen "A cute cat"
360 
361# Custom output path
362zimg gen "A cute cat" --output "my_cat.png"
363 
364# High quality settings
365zimg gen "Landscape view" --width 1920 --height 1080 --steps 20
366 
367# With a specific seed for reproducibility
368zimg gen "A majestic dragon" --seed 12345
369 
370# Select model precision (full, q8, q4)
371zimg gen "A futuristic city" --precision q8
372 
373# Skip writing to history DB
374zimg gen "Quick scratch" --no-history
375```
376 
377### 2. Web Server Mode
378Launch the web interface to generate images interactively.
379 
380```bash
381# Start server on default port (http://localhost:8000)
382zimg serve
383 
384# Start on custom host/port
385zimg serve --host 0.0.0.0 --port 9090
386```
387 
388Once started, open your browser to the displayed URL.
389 
390### 3. MCP Server Mode (Model Context Protocol)
391Run Z-Image Studio as an MCP server:
392 
393```bash
394# stdio transport (ideal for local agents/tools); also available as `zimg mcp`
395zimg-mcp
396 
397# MCP transports are available when you run the web server:
398zimg serve          # Both Streamable HTTP (/mcp) and SSE (/mcp-sse) available
399zimg serve --disable-mcp   # Disable all MCP endpoints
400```
401 
402Available tools: `generate` (prompt to image), `list_models`, and `list_history`. Logs are routed to stderr to keep MCP stdio clean.
403 
404#### Connecting an AI agent (e.g., Claude Desktop) to `zimg-mcp`
4051. Ensure dependencies are installed (`uv sync`) and that `zimg-mcp` is on PATH (installed via `uv tool install .` or run locally via `uv run zimg-mcp`).
4062. In Claude Desktop (or any MCP-aware client), add a local mcp server entry like:
407   ```json
408   {
409     "mcpServers": {
410       "z-image-studio": {
411         "command": "zimg-mcp",
412         "args": [],
413         "env": {}
414       }
415     }
416   }
417   ```
418   Adjust the `command` to a full path if not on PATH. If the agent cannot find the zimg-mcp command, you can also try setting the path in environment.
419 
420   Different agents may have slightly different parameters, for example, cline will timeout fast if you do not explicitly set a timeout parameter. Here is the example for cline:
421   ```json
422   {
423     "mcpServers": {
424       "z-image-studio": {
425         "command": "zimg-mcp",
426         "type": "stdio",
427         "args": [],,
428         "env": {},
429         "disabled": false,
430         "autoApprove": [],
431         "timeout": 300
432       }
433     }
434   }
435   ```
436   Detailed syntax may vary, please refer to the specific agent's documentation.
4373. For Clients that support remote mcp server, configure the client with the streamable Http mcp endpoint URL (meanwhile keep the server up by running `zimg serve`). Here is an example for Gemini CLI:
438   ```json
439   {
440     "mcpServers": {
441       "z-image-studio": {
442         "httpUrl": "http://localhost:8000/mcp"
443       }
444     }
445   }
446   ```
447   Detailed syntax may vary, please refer to the specific agent's documentation.
4484. For legacy SSE , run `zimg serve` and configure the client with the SSE endpoint URL. Here is an example for Cline CLI:
449   ```json
450   {
451     "mcpServers": {
452       "z-image-studio": {
453         "url": "http://localhost:8000/mcp-sse/sse"
454       }
455     }
456   }
457   ```
458   Detailed syntax may vary, please refer to the specific agent's documentation.
4595. The agent will receive tools: `generate`, `list_models`, `list_history`.
460 
461 
462#### MCP Content Structure
463 
464The `generate` tool returns a consistent content array with three items in this order:
465 
4661. **TextContent**: Enhanced metadata including generation info, file details, and preview metadata
467   ```json
468   {
469     "message": "Image generated successfully",
470     "duration_seconds": 1.23,
471     "width": 1280,
472     "height": 720,
473     "precision": "q8",
474     "model_id": "z-image-turbo-q8",
475     "seed": 12345,
476     "filename": "image_12345.png",
477     "file_path": "/absolute/path/to/image_12345.png",
478     "access_note": "Access full image via ResourceLink.uri or this URL",
479     "preview": true,
480     "preview_size": 400,
481     "preview_mime": "image/png"
482   }
483   ```
484   - **SSE/Streamable HTTP Transports**: `url` and `access_note` point to the absolute image URL
485   - **Stdio Transport**: `file_path` and `access_note` point to the local file path
486 
4872. **ResourceLink**: Main image file reference with context-appropriate URI
488   - **SSE/Streamable HTTP Transports**: Absolute URL built from request context, ZIMAGE_BASE_URL, or relative path
489   - **Stdio Transport**: file:// URI for local access
490 
491   URI Building Priority (SSE/Streamable HTTP):
492   1. **Request Context** (via Context parameter) - builds absolute URL from X-Forwarded-* headers
493   2. **ZIMAGE_BASE_URL** environment variable - configured base URL
494   3. **Relative URL** - fallback when no other method available
495   
496   Example with Context parameter:
497   ```python
498   @mcp.tool()
499   async def generate_with_context(..., ctx: Context) -> ...:
500       request = ctx.request_context.request
501       proto = request.headers.get('x-forwarded-proto', 'http')
502       host = request.headers.get('x-forwarded-host', 'localhost')
503       return ResourceLink(uri=f"{proto}://{host}/outputs/image.png", ...)
504   ```
505   ```json
506   {
507     "type": "resource_link",
508     "name": "image_12345.png",
509     "uri": "https://example.com/outputs/image_12345.png",
510     "mimeType": "image/png"
511   }
512   ```
513 
5143. **ImageContent**: Thumbnail preview (base64 PNG, max 400px)
515   ```json
516   {
517     "data": "base64-encoded-png-data",
518     "mimeType": "image/png"
519   }
520   ```
521 
522This structure ensures:
523- ✅ **Consistency**: Same content for both stdio and SSE transports
524- ✅ **Efficiency**: No URL/path duplication across content items
525- ✅ **Flexibility**: ResourceLink provides file access while ImageContent offers immediate preview
526- ✅ **Compatibility**: Follows MCP best practices for structured content types
527 
528## Command Line Arguments
529 
530### Subcommand: `generate` (alias: `gen`)
531| Argument | Short | Type | Default | Description |
532| :--- | :--- | :--- | :--- | :--- |
533| `prompt` | | `str` | Required | The text prompt for image generation. |
534| `--output` | `-o` | `str` | `None` | Custom output filename. Defaults to `outputs/<prompt-slug>.png` inside the data directory. |
535| `--steps` | | `int` | `9` | Number of inference steps. Higher usually means better quality. |
536| `--width` | `-w` | `int` | `1280` | Image width (automatically adjusted to be a multiple of 8). |
537| `--height` | `-H` | `int` | `720` | Image height (automatically adjusted to be a multiple of 8). |
538| `--seed` | | `int` | `None` | Random seed for reproducible generation. |
539| `--precision` | | `str` | `q8` | Model precision (`full`, `q8`, `q4`). `q8` is the default and balanced, `full` is higher quality but slower, `q4` is fastest and uses less memory. |
540| `--lora` | | `str` | `[]` | LoRA filename or path, optionally with strength (`name.safetensors:0.8`). Can be passed multiple times (max 4); strength is clamped to -1.0..2.0. |
541| `--no-history` | | `bool` | `False` | Do not record this generation in the history database. |
542 
543### Subcommand: `serve`
544| Argument | Type | Default | Description |
545| :--- | :--- | :--- | :--- |
546| `--host` | `str` | `0.0.0.0` | Host to bind the server to. |
547| `--port` | `int` | `8000` | Port to bind the server to. |
548| `--reload` | `bool` | `False` | Enable auto-reload (for development). |
549| `--timeout-graceful-shutdown` | `int` | `5` | Seconds to wait for graceful shutdown before forcing exit. |
550| `--disable-mcp` | `bool` | `False` | Disable all MCP endpoints (`/mcp` and `/mcp-sse`). |
551 
552### Subcommand: `models`
553| Argument | Short | Type | Default | Description |
554| :--- | :--- | :--- | :--- | :--- |
555| (None)   |       |       |         | Lists available image generation models and local cache status (cached flag, cache path, cache size). |
556| `list`   |       |       |         | Explicit alias for list behavior (`zimg models list`). |
557| `clear <precision>` | | `str` | Required | Clear local cached files for one precision (`full`, `q8`, `q4`). |
558 
559### Subcommand: `info`
560| Argument | Type | Default | Description |
561| :--- | :--- | :--- | :--- |
562| `--json` | `bool` | `False` | Output application diagnostics as JSON (for scripts/tools). |
563| (none) | | | Shows version, runtime details, resolved data/config/output paths, env overrides, and hardware probe info. |
564 
565### Subcommand: `mcp`
566| Argument | Type | Default | Description |
567| :--- | :--- | :--- | :--- |
568| (none) | | | Stdio-only MCP server (for agents). Use `zimg-mcp` or `zimg mcp`. |
569 
570 
571## Data Directory and Configuration
572 
573By default, Z-Image Studio uses the following directories:
574 
575*   **Data Directory** (Database, LoRAs): `~/.local/share/z-image-studio` (Linux), `~/Library/Application Support/z-image-studio` (macOS), or `%LOCALAPPDATA%\z-image-studio` (Windows).
576*   **Output Directory** (Generated Images): `<Data Directory>/outputs` by default. 
577 
578### Configure the directory
579*   **Config File**: `~/.z-image-studio/config.json` (created on first run after migration).
580    *   Override the data directory with `Z_IMAGE_STUDIO_DATA_DIR`.
581    *   If you want the output directory sit in another location instead of the data directory, you can override it with `Z_IMAGE_STUDIO_OUTPUT_DIR`.
582 
583Directory structure inside Data Directory by default:
584*   `zimage.db`: SQLite database
585*   `loras/`: LoRA models
586*   `outputs/`: Generated image files
587 
588### One-time Migration (automatic)
589On first run without an existing config file, the app migrates legacy data by moving:
590*   `outputs/`, `loras/`, and `zimage.db` from the current working directory (old layout) into the new locations.
591 
592 
593## Screenshots
594 
595![Screenshot 1](docs/images/screenshot1.png)
596*(Screenshot 1: Two column layout with History browser collapsed)*
597 
598![Screenshot 2](docs/images/screenshot2.png)
599*(Screenshot 2: Three column layout with History browser pinned)*
600 
601 
602![Screenshot 3](docs/images/screenshot3.png)
603*(Screenshot 3: Generated Image zoomed to fit the screen)*
604 
605 
606## Development
607 
608### Installation in Project Virtual Environment
609 
6101.  **Clone the repository:**
611    ```bash
612    git clone https://github.com/iconben/z-image-studio.git
613    cd z-image-studio
614    ```
615 
616### To run the source code directly without installation:
617 
6181.  **Run CLI:**
619    ```bash
620    uv run src/zimage/cli.py generate "A prompt"
621    ```
622 
6232.  **Run Server:**
624    ```bash
625    uv run src/zimage/cli.py serve --reload
626    ```
627 
6283.  **Run tests:**
629    ```bash
630    uv run pytest
631    ```
632 
633### Optional: Install in editable mode:**
634    First install it:
635    ```bash
636    uv pip install -e .
637    ```
638 
639    After this, the `zimg` command is available **inside this virtual environment**:
640 
641    Then use the zimg command in either ways:
642 
643    Using `uv` (recommended):
644    ```bash
645    uv run zimg generate "A prompt"
646    ```
647 
648    or use in more traditional way:
649    ```bash
650    source .venv/bin/activate  # Under Windows: .venv\Scripts\activate
651    zimg serve
652    ```
653 
654### Optional: Override the folder settings with environment variables
655     If you do not want your development data mess up your production data,
656     You can define environment variable Z_IMAGE_STUDIO_DATA_DIR to change the data folder for
657     You can also define environment variable Z_IMAGE_STUDIO_OUTPUT_DIR to change the output folder to another separate folder
658 
659### Docker Development
660 
661Build and run with Docker:
662 
663```bash
664# Build the image
665docker build -t z-image-studio:dev .
666 
667# Run with source mounted for hot-reload
668docker run -d \
669  --name zimg-dev \
670  -p 8000:8000 \
671  -v $(pwd)/src:/app/src \
672  -v zimg-data:/data \
673  -e DEBUG=1 \
674  -e ZIMAGE_ENABLE_TORCH_COMPILE=1 \
675  z-image-studio:dev
676```
677 
678Or use Docker Compose:
679 
680```bash
681docker compose up -d
682```
683 
684### Environment Variables
685| Variable | Description |
686| :--- | :--- |
687| `ZIMAGE_ENABLE_TORCH_COMPILE` | Force enable `torch.compile` optimization (experimental). By default disabled for Python 3.12+ due to known compatibility issues. Can be set to `1` via environment variable or config file (`~/.z-image-studio/config.json`) to enable at your own risk. |
688| `Z_IMAGE_STUDIO_DATA_DIR` | Override the default data directory location. |
689| `Z_IMAGE_STUDIO_OUTPUT_DIR` | Override the default output directory location. |
690## Notes
691 
692*   **Guidance Scale**: The script hardcodes `guidance_scale=0.0` as required by the Turbo model distillation process.
693*   **Safety Checker**: Disabled by default to prevent false positives and potential black image outputs during local testing.
694 
695For detailed architecture and development guidelines, see [docs/architecture.md](docs/architecture.md).
696