Skip to content
Back to search

z-image-studio

A Cli, a webUI, and a MCP server for the Z-Image-Turbo text-to-image generation model (Tongyi-MAI/Z-Image-Turbo base model as well as quantized models)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iconben--z-image-studio/badge.svg)](/listings/iconben--z-image-studio)

HTML

<a href="/listings/iconben--z-image-studio"><img src="/api/listings/iconben--z-image-studio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 697 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.