# Fooocus User Guide

Fooocus is a free, offline, open-source image generator built on the **Stable Diffusion XL (SDXL)** architecture and a [Gradio](https://www.gradio.app/) web interface. It is designed around one idea: you focus on *prompts and images*, and Fooocus handles the rest. Like Midjourney, you do not need to tune samplers, schedulers, or guidance scales to get a good result — but unlike Midjourney, everything runs locally on your own machine, for free, with no account and no internet dependency after the models are downloaded.

This guide covers everything you can *do* with Fooocus: installing it, generating your first image, and using every generation mode, style, and advanced control the interface exposes.

> [!NOTE]
> Fooocus is currently in **limited long-term support (LTS) — bug fixes only**. It is built entirely on SDXL and there are no current plans to adopt newer architectures (such as Flux). If you need newer models, the project authors point to [WebUI Forge](https://github.com/lllyasviel/stable-diffusion-webui-forge), [ComfyUI/SwarmUI](https://github.com/comfyanonymous/ComfyUI), or one of the community forks. Fooocus itself remains fully functional and stable for SDXL generation.

> [!CAUTION]
> Many fake websites impersonate Fooocus (e.g. "fooocus.com", "fooocus.net", "fooocus.ai", "fooocus.org", "fooocus.pro", "fooocus.one"). **None of these are official.** Fooocus is a 100% non-commercial, offline, open-source program. Download only from the official GitHub repository: [github.com/lllyasviel/Fooocus](https://github.com/lllyasviel/Fooocus).

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Requirements](#2-requirements)
3. [Installation](#3-installation)
4. [The Interface at a Glance](#4-the-interface-at-a-glance)
5. [Writing Prompts](#5-writing-prompts)
6. [Everyday Generation Tasks](#6-everyday-generation-tasks)
7. [Working From an Input Image](#7-working-from-an-input-image)
8. [Styles](#8-styles)
9. [Performance Modes](#9-performance-modes)
10. [Presets and Editions](#10-presets-and-editions)
11. [Advanced Settings](#11-advanced-settings)
12. [LoRAs, Embeddings, and Wildcards](#12-loras-embeddings-and-wildcards)
13. [Output, History, and Metadata](#13-output-history-and-metadata)
14. [Command-Line Options](#14-command-line-options)
15. [Troubleshooting](#15-troubleshooting)
16. [FAQ](#16-faq)
17. [Reference Tables](#17-reference-tables)

---

## 1. Quick Start

If you are on Windows and just want an image as fast as possible:

1. Download the official Windows package (a `.7z` archive — see [Installation](#3-installation)).
2. Extract it.
3. Double-click **`run.bat`**.
4. Wait for the first-run model download to finish (a browser tab opens automatically).
5. Type a prompt — for example `house in garden` — into the prompt box.
6. Click **Generate**.

That is the entire workflow. Fooocus deliberately limits the number of clicks between "download" and "first image" to fewer than three. You do **not** need to choose a model, a sampler, or any numeric setting to begin.

> [!TIP]
> Your prompt can be as short as `house in garden` or as long as 1000 words. Fooocus runs an offline GPT-2-based prompt-expansion engine (the **Fooocus V2** style, enabled by default) plus a large set of sampling improvements, so results look polished regardless of prompt length.

---

## 2. Requirements

Fooocus runs on **Windows**, **Linux**, and (with extra fallbacks) **macOS**, and supports NVIDIA, AMD, and Intel GPUs to varying degrees.

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| GPU (NVIDIA) | 4 GB VRAM | 6 GB+ VRAM |
| System RAM | 8 GB (requires swap/virtual memory) | 16 GB+ |
| Free disk space | ~40 GB free **per drive** if you hit memory errors | 40 GB+ |
| Python (manual installs) | **3.10** | 3.10 |
| OS | Windows 10/11, modern Linux, macOS | — |

> [!IMPORTANT]
> The 4 GB VRAM / 8 GB RAM minimum relies on Windows **Virtual Swap** (the system page file), which is enabled by default in most Windows installations. If you have disabled it, or you see `RuntimeError: CPUAllocator`, re-enable virtual memory and make sure you have at least **40 GB free space on each drive**.

> [!NOTE]
> AMD GPU support is in **beta** and is not intensively tested. Intel and macOS (Apple Silicon, via MPS fallback) work but are slower. See [Installation](#3-installation) for platform-specific steps.

A reference benchmark from the project: a laptop with **16 GB RAM** and a **6 GB VRAM NVIDIA 3060** generates at roughly **1.35 seconds per iteration**.

---

## 3. Installation

### Windows (one-click package) — recommended

=== "Standard"

    1. Download the official package: **[Fooocus_win64_2-5-0.7z](https://github.com/lllyasviel/Fooocus/releases/download/v2.5.0/Fooocus_win64_2-5-0.7z)** from the GitHub Releases page.
    2. Extract the `.7z` archive (use [7-Zip](https://www.7-zip.org/) if needed).
    3. Run **`run.bat`**.

    On first launch, Fooocus automatically downloads the default model set into `Fooocus\models\checkpoints\`. A browser tab opens when the server is ready.

=== "Anime / Realistic editions"

    The Windows package also ships **`run_anime.bat`** and **`run_realistic.bat`**. These launch Fooocus with a different model preset (and download different models on first use):

    ```text
    run.bat            → default edition (Juggernaut XL)
    run_anime.bat      → anime edition (AnimaPencil XL)
    run_realistic.bat  → realistic edition (Realistic Stock Photo)
    ```

> [!NOTE]
> If you see **`MetadataIncompleteBuffer`** or **`PytorchStreamReader`** errors, your model files are corrupted — delete them and let Fooocus download them again.

### Linux (Anaconda / Miniconda)

```bash
git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus
conda env create -f environment.yaml
conda activate fooocus
pip install -r requirements_versions.txt
python entry_with_update.py
```

Expected first-run output (abbreviated):

```text
[System ARGV] ['entry_with_update.py']
Python 3.10.x
Fooocus version: 2.5.5
...downloading default model...
App started successful. Use the app with http://127.0.0.1:7865
```

### Linux (Python venv)

```bash
git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus
python3 -m venv fooocus_env
source fooocus_env/bin/activate
pip install -r requirements_versions.txt
python entry_with_update.py
```

### Linux (native system Python)

```bash
git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus
pip3 install -r requirements_versions.txt
python3 entry_with_update.py
```

### Linux (AMD GPUs)

Install as above, then replace PyTorch with the ROCm build:

```bash
pip uninstall torch torchvision torchaudio torchtext functorch xformers
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.6
```

### Google Colab

Open the [official Colab notebook](https://colab.research.google.com/github/lllyasviel/Fooocus/blob/main/fooocus_colab.ipynb). Modify the last line to choose an edition:

```python
!python entry_with_update.py --share --always-high-vram
!python entry_with_update.py --share --always-high-vram --preset anime
!python entry_with_update.py --share --always-high-vram --preset realistic
```

> [!TIP]
> On free-tier Colab, `--always-high-vram` shifts memory from RAM to VRAM and gives the best balance on the default T4 instance. The refiner is disabled by default on Colab to conserve resources; basic text-to-image always works.

### What gets downloaded on first run

Fooocus ships **no model weights**. On first launch (and whenever you switch to a preset whose model you don't have yet), it downloads what it needs from Hugging Face automatically:

- The **default checkpoint** for the active preset (e.g. `juggernautXL_v8Rundiffusion.safetensors`, ~6.6 GB).
- The **Fooocus V2 prompt-expansion** model (`fooocus_expansion`).
- **VAE approximation** preview models.
- On demand: the **inpaint** model (`inpaint_v26.fooocus.patch`, ~1.28 GB the first time you inpaint), **ControlNet**, **Image Prompt** adapters, **upscaler**, and **SAM** masking models — each downloaded the first time the relevant feature is used.

If you already have these files, copy them into the matching `models\` subfolder to skip the download.

---

## 4. The Interface at a Glance

When Fooocus opens in your browser, you see a deliberately minimal layout:

```text
┌─────────────────────────────────────────────┬───────────────┐
│  Image gallery / live preview                │               │
│                                              │   Advanced    │
│  ┌────────────────────────────┐  ┌────────┐  │   panel       │
│  │ Prompt textbox             │  │Generate│  │  (Settings /  │
│  └────────────────────────────┘  └────────┘  │   Styles /    │
│  [ ] Input Image  [ ] Enhance  [ ] Advanced  │   Models /    │
│                                              │   Advanced)   │
└─────────────────────────────────────────────┴───────────────┘
```

The three checkboxes under the prompt box reveal more of the interface:

| Checkbox | Reveals |
|----------|---------|
| **Input Image** | Tabs for working from an existing image: Upscale or Variation, Image Prompt, Inpaint or Outpaint, Describe, Enhance, Metadata. |
| **Enhance** | A post-generation enhancement pipeline (per-region detailing and upscaling). |
| **Advanced** | The right-hand panel with **Settings**, **Styles**, **Models**, and **Advanced** tabs. |

By default, only the prompt box and **Generate** button are needed. Everything else is optional.

> [!TIP]
> During generation you can click **Stop** to cancel the current task, or **Skip** to abandon the current image and move to the next one in the batch.

---

## 5. Writing Prompts

The prompt box is the heart of Fooocus. A few syntax features (borrowed from AUTOMATIC1111 / Civitai conventions) give you fine control.

### Multiple prompts

Each **non-empty line** in the prompt box is treated as a separate prompt fragment and combined. This is the Fooocus equivalent of Midjourney's `::` multi-prompt syntax — just use multiple lines.

### Prompt weighting

Increase or decrease the influence of words with parentheses and a multiplier:

```text
I am (happy:1.5)
a (red:1.3) car on a (quiet:0.8) street
```

Fooocus uses A1111's reweighting algorithm, so prompts copied directly from Civitai behave as their authors intended.

### Embeddings

Reference a textual-inversion embedding inline:

```text
a portrait, (embedding:my_embedding_file:1.1)
```

The embedding file must exist in your `models\embeddings\` folder.

### Negative prompts

Open the **Advanced** panel → **Settings** to find the **Negative Prompt** box. Describe what you do **not** want to see:

```text
blurry, low quality, watermark, extra fingers
```

> [!TIP]
> You usually don't need a long negative prompt. The default styles (especially `Fooocus Negative`, used by the realistic preset) already suppress common artifacts.

---

## 6. Everyday Generation Tasks

### Generate an image from text (txt2img)

1. Type your prompt.
2. (Optional) Open **Advanced → Settings** to set the aspect ratio, image count, and performance.
3. Click **Generate**.

Generated images appear in the gallery. With **Image Number** greater than 1, Fooocus produces a batch and shows a grid.

### Choose an aspect ratio

Open **Advanced → Settings → Aspect Ratios**. Fooocus offers the full set of SDXL-optimal resolutions, displayed as `width × height` with the simplified ratio. The default is `1152 × 896` (a 9:7 landscape). See the [Reference Tables](#17-reference-tables) for the complete list.

### Generate several images at once

In **Advanced → Settings**, set **Image Number** (1–32 by default). Each image in the batch uses the seed plus its index, so a batch explores nearby variations unless you disable seed increment.

### Control the seed

By default **Random** is checked and a new seed is used every time. Uncheck **Random** to type a fixed **Seed** value and reproduce a result exactly.

### Pick an output format

In **Advanced → Settings → Output Format**, choose `png`, `jpeg`, or `webp`. PNG is the default and embeds full generation metadata.

---

## 7. Working From an Input Image

Check **Input Image** to reveal six tabs. Each takes an uploaded image and does something different with it.

### Upscale or Variation

Upload an image, then pick a method:

| Method | What it does |
|--------|--------------|
| **Vary (Subtle)** | Re-generates a near-copy with small changes (denoising strength ≈ 0.5). |
| **Vary (Strong)** | Re-generates with larger changes (denoising strength ≈ 0.85). |
| **Upscale (1.5×)** | Upscales to 1.5× then refines with diffusion. |
| **Upscale (2×)** | Upscales to 2× then refines with diffusion. |
| **Upscale (Fast 2×)** | Pure upscaler, no diffusion refinement — fastest. |

> [!NOTE]
> When an upscaled image would exceed roughly 2800px on its longer dimension, Fooocus returns the super-resolution result directly (skipping diffusion), because direct SR at 4K typically looks better than re-diffusing.

### Image Prompt

Use an existing image to influence a new generation. Upload one or more reference images and choose a **Type** per image:

| Type | Purpose |
|------|---------|
| **ImagePrompt** | General "use this image as inspiration" (Fooocus Image Mixture Engine). |
| **PyraCanny** | Follow the edges/structure of the reference (Canny-style ControlNet). |
| **CPDS** | Follow the depth/contrast structure of the reference. |
| **FaceSwap** | Transfer a face from the reference into the generated image. |

Each image has **Stop At** and **Weight** sliders (revealed by the per-image **Advanced** checkbox) to tune how strongly and how long it influences the result. Sensible defaults are applied per type.

### Inpaint or Outpaint

Upload an image and paint a mask over the area to change.

- **Inpaint or Outpaint (default)** — repaint the masked area, or extend the canvas using the **Outpaint Direction** checkboxes (Left / Right / Top / Bottom).
- **Improve Detail (face, hand, eyes, etc.)** — refine details in the masked region.
- **Modify Content (add objects, change background, etc.)** — make larger content changes.

Optional **Advanced Masking** lets you upload a separate mask or auto-generate one with a segmentation model (`u2net`, `isnet`, `sam`, etc.) and a text detection prompt (e.g. `face`, `hand`).

> [!TIP]
> The **Inpaint Additional Prompt** box describes what you want *in the masked area* specifically — it is combined with your main prompt. There is a quick-list of common prompts (`detailed hand`, `beautiful eyes`, …).

### Describe

Upload an image to generate a text prompt *from* it (image-to-text). Choose a content type:

- **Photograph** — uses a photo-oriented interrogator.
- **Art/Anime** — uses an anime-oriented tagger.

Check **Apply Styles** to also suggest matching styles. The generated description is written into the prompt box, ready to generate from.

### Enhance

The **Enhance** tab (and the standalone **Enhance** checkbox) runs a multi-step post-processing pipeline that detects regions (faces, hands, eyes, …) and re-renders them at higher detail, optionally followed by an upscale. You get up to several independent enhancement "slots", each with its own detection prompt, positive/negative prompt, and inpaint settings.

### Metadata

Upload an image **previously created by Fooocus** to read back the exact parameters used (prompt, model, seed, styles, sampler, etc.). Click **Apply Metadata** to load those parameters into the interface so you can reproduce or tweak the result.

---

## 8. Styles

Styles are reusable prompt/negative-prompt templates. Open **Advanced → Styles** to browse and search them. You can apply any number at once; they stack.

Notable built-in styles:

| Style | Effect |
|-------|--------|
| **Fooocus V2** | The offline GPT-2 prompt-expansion engine. Enabled by default — it rewrites and enriches your prompt for better results. |
| **Fooocus Enhance** | General quality boost (default in the standard preset). |
| **Fooocus Sharp** | Increases perceived sharpness (default in the standard preset). |
| **Fooocus Negative** | Adds a strong negative prompt (used by the realistic preset). |
| **Fooocus Photograph / Cinematic / Masterpiece / Pony / Semi Realistic** | Genre/look presets. |
| **Random Style** | Picks a random style per image — great for exploration. |

Fooocus ships several hundred styles across six built-in style packs (SAI, MRE, TWRI, Diva, Marc K3nt3l, and the Fooocus pack). Use the **search box** at the top of the Styles tab to filter by name.

> [!TIP]
> A style can contain a `{prompt}` placeholder. If it does, your prompt is inserted *into* the style template; if it doesn't, your prompt is prepended. This is handled automatically — you only need to pick styles.

---

## 9. Performance Modes

The **Performance** selector (in **Advanced → Settings**) trades speed for quality by changing the number of sampling steps and, for the fast modes, loading an acceleration LoRA automatically.

| Mode | Steps | Notes |
|------|-------|-------|
| **Quality** | 60 | Highest fidelity, slowest. |
| **Speed** | 30 | The default — balanced. |
| **Extreme Speed** | 8 | Uses an LCM LoRA (auto-downloaded). Disables the refiner and several quality knobs. |
| **Lightning** | 4 | Uses an SDXL-Lightning LoRA (auto-downloaded). |
| **Hyper-SD** | 4 | Uses a Hyper-SD LoRA (auto-downloaded). |

> [!IMPORTANT]
> Extreme Speed, Lightning, and Hyper-SD are **restricted-feature** modes. When selected, Fooocus forces the refiner off and overrides CFG/guidance, sharpness, and ADM settings to the values those acceleration methods require. This is expected behavior — those knobs have no effect in these modes.

---

## 10. Presets and Editions

A **preset** bundles a default model, default styles, default performance, and a set of models to auto-download. Fooocus ships several:

| Preset | Base model | Default styles | Notes |
|--------|-----------|----------------|-------|
| `default` (initial) | Juggernaut XL v8 | Fooocus V2 + Enhance + Sharp | General-purpose. CFG 4.0. |
| `anime` | AnimaPencil XL v5 | Fooocus V2 + Semi Realistic + Masterpiece | Anime/illustration. CFG 6.0. |
| `realistic` | Realistic Stock Photo v2 | Fooocus V2 + Photograph + Negative | Photoreal. CFG 3.0, film LoRA. |
| `lcm` | Juggernaut XL v8 | Fooocus V2 + Enhance + Sharp | Extreme Speed mode by default. |
| `lightning` | Juggernaut XL v8 | Fooocus V2 + Enhance + Sharp | Lightning mode by default. |
| `playground_v2.5` | Playground v2.5 | Fooocus V2 | Uses the `edm_playground_v2.5` scheduler. |
| `pony_v6` | Pony Diffusion V6 XL | Fooocus Pony | Includes a matching VAE. |
| `sai` | SDXL base 1.0 + refiner | Fooocus V2 + Cinematic | Stock SDXL with refiner. CFG 7.0. |

Choose a preset three ways:

1. **At launch** with `--preset anime` (or `realistic`, `lcm`, …).
2. **The edition launchers** on Windows: `run_anime.bat`, `run_realistic.bat`.
3. **In the browser**, via the **Preset** dropdown in **Advanced → Settings** (available since Fooocus 2.3.0).

> [!NOTE]
> Switching presets in the browser may download a new model. If you don't have it and haven't passed `--always-download-new-model`, Fooocus falls back to a `previous_default_models` entry you already have and tells you in the terminal. On Colab, a preset switch can cause a 60-second timeout — wait for the download, then switch the preset to `initial` and back, or reload the page.

---

## 11. Advanced Settings

Open **Advanced → Advanced** (the inner Advanced tab) for fine control. You rarely need these, but they're there.

| Setting | Default | What it does |
|---------|---------|--------------|
| **Guidance Scale (CFG)** | 4.0 (preset-dependent) | How strongly the image follows the prompt. |
| **Image Sharpness** | 2.0 | Post-sampling sharpness. |
| **CFG Mimicking from TSNR** | 7.0 | Adaptive CFG target. |
| **Sampler** | `dpmpp_2m_sde_gpu` | The sampling algorithm. |
| **Scheduler** | `karras` | The noise schedule. |
| **VAE** | Default (model) | Override the VAE used for decoding. |
| **CLIP Skip** | 2 | How many final CLIP layers to skip. |
| **Refiner Switch** | 0.5–0.8 | Fraction of steps before switching to the refiner model. |
| **FreeU** | off | Enable the FreeU UNet trick (B1/B2/S1/S2 sliders). |
| **ADM Guidance** | 1.5 / 0.8 / 0.3 | Positive/negative/end ADM scaling. |
| **Overwrite** sliders | -1 (off) | Force a specific step count, switch step, width, height, or upscale/vary strength. |
| **Canny low/high threshold** | — | PyraCanny edge-detection thresholds. |
| **ControlNet Softness** | 0.25 | Softens ControlNet influence. |

> [!WARNING]
> The Overwrite sliders are powerful but easy to misuse. A value of `-1` means "don't overwrite". Setting `Overwrite Step` to a low number, for example, will make every generation use that exact step count regardless of the Performance mode.

See the [Admin Guide](lllyasviel__Fooocus__AdminGuide.md) for the architecture behind these settings and how they map to the underlying diffusion pipeline.

---

## 12. LoRAs, Embeddings, and Wildcards

### LoRAs

Open **Advanced → Models** to enable up to five **LoRA** slots. Each slot has an enable toggle, a model dropdown, and a weight slider (default range -2 to 2). Drop `.safetensors` LoRA files into `models\loras\`.

You can also reference a LoRA inline in your prompt:

```text
a fantasy castle <lora:my_lora_file:0.8>
```

### Embeddings

Place textual-inversion `.safetensors`/`.pt` files in `models\embeddings\` and reference them with `(embedding:file_name:1.1)` as shown in [Writing Prompts](#5-writing-prompts).

### Wildcards

Wildcards inject random or sequential words into prompts. Two mechanisms exist:

**1. Wildcard files** — text files in the `wildcards\` folder. Reference one by name with double underscores:

```text
a portrait of a __color__ haired person
```

This reads a random line from `wildcards\color.txt`. Fooocus ships wildcard files (animal, color, artist, etc.) and recurses up to 64 levels deep.

**2. Inline arrays** — pick one option per image from a bracketed list:

```text
a [[red, green, blue]] sports car
```

Across a batch, Fooocus cycles through the array options deterministically.

> [!TIP]
> Check **Read Wildcards in Order** (in Advanced) to step through wildcard file lines sequentially instead of randomly — useful for systematic exploration.

---

## 13. Output, History, and Metadata

### Where images go

Generated images are saved to the `outputs\` folder, organized by date, alongside an HTML log of each session. Use the **History Log** link (in Advanced → Settings) to open the browsable log in a new tab.

### Metadata

By default Fooocus can embed full generation parameters into each image so you can reproduce it later. Two schemes are available (**Advanced → Settings**):

| Scheme | Format |
|--------|--------|
| **fooocus** | JSON embedded in the image. |
| **a1111** | AUTOMATIC1111-style plain-text parameters. |

Load metadata back via the **Input Image → Metadata** tab.

> [!NOTE]
> If you launched with `--disable-metadata`, no parameters are written. If you launched with `--disable-image-log`, images and logs are not written to the `outputs\` folder at all (only the temporary Gradio copy is kept).

---

## 14. Command-Line Options

Pass these to `run.bat`, `entry_with_update.py`, or `launch.py`. The most useful end-user options are below; the full list (including engine/VRAM/precision flags) is in the [Admin Guide](lllyasviel__Fooocus__AdminGuide.md).

| Flag | Effect |
|------|--------|
| `--preset NAME` | Start with a preset (`anime`, `realistic`, `lcm`, …). |
| `--language NAME` | Use `language/NAME.json` to translate the UI. |
| `--theme dark` / `--theme light` | Force a UI theme. |
| `--share` | Create a public Gradio share link. |
| `--listen` | Listen on the network (open a remote port). |
| `--port N` | Set the server port (default `7865`). |
| `--always-high-vram` | Favor VRAM over RAM (recommended on cloud/T4). |
| `--always-low-vram` / `--always-no-vram` | Reduce VRAM use on low-memory GPUs. |
| `--disable-offload-from-vram` | Keep models in VRAM (some Mac users need this). |
| `--disable-preset-selection` | Hide the in-browser preset dropdown. |
| `--always-download-new-model` | Download the newest preset models instead of falling back. |
| `--disable-preset-download` | Don't download preset models at all. |
| `--disable-image-log` | Don't write images/logs to `outputs\`. |
| `--disable-metadata` | Don't embed metadata in images. |
| `--gpu-device-id N` | Select a specific GPU. |

Example:

```bash
python entry_with_update.py --preset realistic --listen --always-high-vram
```

---

## 15. Troubleshooting

The format below is: the exact symptom, why it happens, and how to fix it. Many of these are drawn from real community reports.

### Error: `RuntimeError: CUDA error: no kernel image is available` / `sm_120 is not compatible`

**Cause:** Your GPU is newer than the bundled PyTorch supports. Fooocus pins **PyTorch 2.1.0**, which predates the compute capability of GPUs like the **RTX 5090 / 5080 / 5050** (`sm_120`). (Reported in issues #3862, #4141, #4142, #4164.)

**Solution:** Manually install a newer PyTorch build that supports your GPU, then launch with a manual (non-package) install:

```bash
pip install --upgrade torch torchvision --index-url https://download.pytorch.org/whl/cu124
python entry_with_update.py
```

**Prevention:** On brand-new GPU generations, expect to upgrade PyTorch beyond the pinned version.

### Error: `ImportError: numpy.core.multiarray failed to import`

**Cause:** A NumPy version mismatch — usually a newer NumPy (2.x) got installed over the pinned `numpy==1.26.4`. (Issues #4167, #4150.)

**Solution:**

```bash
pip install "numpy==1.26.4"
```

**Prevention:** Don't `pip install --upgrade` packages into the Fooocus environment unless you know they're compatible.

### Error: `RuntimeError: CPUAllocator`

**Cause:** Not enough system memory / page file. Fooocus relies on virtual swap to meet its memory needs on low-RAM machines.

**Solution:** Enable Windows virtual memory (page file) and ensure **at least 40 GB free on each drive**. See the instructions linked from the project README.

### Error: `MetadataIncompleteBuffer` or `PytorchStreamReader failed`

**Cause:** A model file (checkpoint, LoRA, VAE) is corrupted or only partially downloaded.

**Solution:** Delete the offending file from `models\` and let Fooocus re-download it, or download it manually from the official Hugging Face source.

### Generation is extremely slow

**Cause:** Several possibilities — wrong VRAM mode, or a known NVIDIA driver regression.

**Solution:**
- Some NVIDIA drivers **above version 532** are reported to be up to 10× slower than driver **531**. Consider the 531 driver if you see very long generation times.
- On low-VRAM GPUs, try `--always-low-vram`. On cloud GPUs (T4), use `--always-high-vram`.

### Fooocus won't start / ASGI `dict is unhashable` error

**Cause:** A dependency/version drift in the environment (reported in #4180, #4181, #4162 — `requirements_versions.txt` pins can go stale over time).

**Solution:** Recreate the environment from a clean `requirements_versions.txt`, or use the official Windows package which bundles a known-good Python and dependency set.

### Colab disconnects or times out

**Cause:** Free-tier Colab has limited resources; "big" features (image prompt, refiner) can exceed them. (Issues #4163, #4169.)

**Solution:** Use `--always-high-vram`, keep the refiner disabled (Colab default), and stick to basic text-to-image on free tier. After a preset switch, wait for downloads, then toggle the preset to `initial` and back, or reload the page.

### AMD GPU can't generate anything

**Cause:** AMD support is beta; the default PyTorch is the CUDA build.

**Solution:** Install the ROCm PyTorch build (see [Installation → Linux AMD](#linux-amd-gpus)). On Windows AMD, try `--directml`. Note that `--gpu-device-id` has no effect when combined with `--directml` (issue #4024).

### Outputs not saving

**Cause:** You launched with `--disable-image-log`, or the output path isn't writable.

**Solution:** Remove `--disable-image-log`, or set a writable path with `--output-path`.

---

## 16. FAQ

**Q: Do I need to choose a model, sampler, or settings to start?**
No. Fooocus is designed so that a prompt and the **Generate** button are all you need. Defaults are tuned per preset.

**Q: Does Fooocus need an internet connection?**
Only to download models the first time (and to auto-update on launch). Once models are present, generation is fully offline.

**Q: Where do I put my own models?**
Checkpoints → `models\checkpoints\`, LoRAs → `models\loras\`, embeddings → `models\embeddings\`, VAEs → `models\vae\`. Then refresh in **Advanced → Models**.

**Q: How do I get anime or photorealistic results?**
Use the `anime` or `realistic` preset (or the `run_anime.bat` / `run_realistic.bat` launchers). They set the right model and styles automatically.

**Q: How do I reproduce an image exactly?**
Uncheck **Random**, set the same **Seed**, and keep the same model, styles, and settings. Or load the original image in the **Metadata** tab and click **Apply Metadata**.

**Q: What's the difference between Speed and Quality?**
Step count: Speed uses 30 steps, Quality uses 60. Quality is slower but more refined. Extreme Speed / Lightning / Hyper-SD use 4–8 steps with acceleration LoRAs for near-instant results.

**Q: Can I generate multiple images at once?**
Yes — set **Image Number** (up to 32) in Advanced → Settings.

**Q: How do I use a face from a photo?**
Input Image → Image Prompt, upload the face photo, set its Type to **FaceSwap**.

**Q: Can I extend an image beyond its borders?**
Yes — Input Image → Inpaint or Outpaint, then check the **Outpaint Direction** (Left/Right/Top/Bottom) boxes and Generate.

**Q: What does the "Fooocus V2" style do?**
It's an offline GPT-2-based prompt-expansion engine that enriches your prompt automatically. It's on by default and is the main reason short prompts still produce good images.

**Q: How do I make the UI another language?**
Place a `language/yourlang.json` translation file and launch with `--language yourlang`.

**Q: Is my prompt or image sent anywhere?**
No. Everything runs locally. The only network activity is model downloads and the launch-time auto-update check (and a Gradio share link if you pass `--share`).

**Q: How do I share Fooocus with others on my network or the internet?**
Use `--listen` for your local network (with `--port`), or `--share` for a temporary public Gradio link. For real exposure, set up authentication — see the [Admin Guide](lllyasviel__Fooocus__AdminGuide.md).

**Q: Why did my fast-mode CFG/sharpness settings get ignored?**
Extreme Speed, Lightning, and Hyper-SD override those settings by design. Switch back to Speed or Quality to control them.

**Q: My GPU is brand new and nothing works. Why?**
The bundled PyTorch 2.1.0 may not support your GPU's compute capability yet. Upgrade PyTorch — see [Troubleshooting](#error-runtimeerror-cuda-error-no-kernel-image-is-available--sm_120-is-not-compatible).

**Q: Where is the official download? I see lots of "fooocus" sites.**
Only [github.com/lllyasviel/Fooocus](https://github.com/lllyasviel/Fooocus). All `fooocus.*` domains are fake.

---

## 17. Reference Tables

### Aspect ratios (width × height)

```text
704×1408   704×1344   768×1344   768×1280   832×1216   832×1152
896×1152   896×1088   960×1088   960×1024   1024×1024  1024×960
1088×960   1088×896   1152×896*  1152×832   1216×832   1280×768
1344×768   1344×704   1408×704   1472×704   1536×640   1600×640
1664×576   1728×576
```
`*` = default for the standard preset.

### Performance modes

| Mode | Steps | Upscale steps | Acceleration LoRA |
|------|-------|---------------|-------------------|
| Quality | 60 | 36 | — |
| Speed | 30 | 18 | — |
| Extreme Speed | 8 | 8 | LCM |
| Lightning | 4 | 4 | SDXL-Lightning |
| Hyper-SD | 4 | 4 | Hyper-SD |

### Upscale / Variation methods

| Method | Behavior |
|--------|----------|
| Vary (Subtle) | Denoise ≈ 0.5 |
| Vary (Strong) | Denoise ≈ 0.85 |
| Upscale (1.5×) | Upscale + diffusion refine |
| Upscale (2×) | Upscale + diffusion refine |
| Upscale (Fast 2×) | Upscaler only, no diffusion |

### Image Prompt types

| Type | Use |
|------|-----|
| ImagePrompt | General visual inspiration |
| PyraCanny | Follow edges/structure |
| CPDS | Follow depth/contrast |
| FaceSwap | Transfer a face |

### Output formats

`png` · `jpeg` · `webp`

### Samplers (common)

`dpmpp_2m_sde_gpu` (default) · `euler` · `euler_ancestral` · `dpmpp_2m` · `dpmpp_sde_gpu` · `dpmpp_3m_sde_gpu` · `lcm` · `tcd` · `restart` · `ddim` · `uni_pc` (plus more — see Advanced)

### Schedulers

`karras` (default) · `normal` · `exponential` · `sgm_uniform` · `simple` · `ddim_uniform` · `lcm` · `turbo` · `align_your_steps` · `tcd` · `edm_playground_v2.5`

---

_Generated June 2026 from lllyasviel/Fooocus at ae05379. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._