Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lllyasviel/Fooocus/llms.txt

Use this file to discover all available pages before exploring further.

Most Fooocus issues fall into a few categories: insufficient system swap (the single most common root cause), GPU driver problems, and corrupted model files. Work through the accordion sections below to find your specific error and its solution. If your error is not listed, check that you are using the official installation guide — incorrect third-party tutorials are a frequent source of problems.
All of the following errors share the same root cause — insufficient system swap space:
  • RuntimeError: CPUAllocator
  • Segmentation Fault
  • Aborted
  • core dumped
  • Killed
  • ^C, then quit
  • adm 2816, then stuck
  • Connection errored out / Error 1006 / WinError 10060 / Read timed out
  • Model loading is extremely slow (more than 1 minute)
  • No error visible — the console closes in a flash
Solution: Ensure you have at least 40 GB of free disk space so the operating system can create adequate swap. See the System Swap section below for detailed setup steps.
If you have more than 64 GB of RAM, you may not need any system swap at all — but this is not guaranteed. The 40 GB free space rule is the safe, reliable baseline.
The model loads into memory and then the process stalls indefinitely without generating anything.Cause: Insufficient system swap space.Solution: Free up at least 40 GB of disk space or explicitly configure a virtual memory page file. See the System Swap section below.
MetadataIncompleteBuffer
PytorchStreamReader failed reading zip archive: failed finding central directory
Cause: One or more model files are corrupted, usually from an interrupted download.Solution: Fooocus will automatically re-download corrupted models on the next launch if your internet connection is working. The console prints the model URL and destination path each time a download is triggered, so you can also download the file manually and place it in the correct folder.
Image generation takes far longer than expected — much slower than the hardware should be capable of.There are two common causes:
  1. Two Fooocus instances running simultaneously. Check your task manager / process list and close any duplicate python processes running Fooocus.
  2. Nvidia driver version above 532. A known issue with Nvidia drivers newer than 532 can make generation 10× slower than driver 531.
Solution for the driver issue: Downgrade to Nvidia driver 531:
torch.cuda.OutOfMemoryError: CUDA out of memory.
on a GPU with 8 GB of VRAM.Cause: This is likely a bug in Fooocus. 8 GB VRAM is above the minimum requirement and should be sufficient.Solution: Open a GitHub issue and include your GPU model, driver version, and the full error traceback.
torch.cuda.OutOfMemoryError: CUDA out of memory.
on a GPU with 6 GB of VRAM.Cause: Very likely a bug. 6 GB VRAM should be sufficient for Fooocus.Solution: Open a GitHub issue as soon as possible with your full system details and error traceback.
torch.cuda.OutOfMemoryError: CUDA out of memory.
on a 4 GB VRAM GPU that supports Float16, such as the RTX 3050.Cause: This is a bug. RTX cards with 4 GB VRAM and Float16 support are within the minimum requirements.Solution: Open a GitHub issue immediately with your GPU model and full error output.
torch.cuda.OutOfMemoryError: CUDA out of memory.
on an older GPU with 4 GB VRAM that does not support Float16, such as the GTX 960.Cause: Supporting SDXL on GPUs without Float16 is extremely difficult. This GPU is at or below the practical limit for running Fooocus.Solution: Fooocus may not be usable on this device. You can try opening a GitHub issue, but consider using SD 1.5 via Automatic1111 or other software that supports older hardware.
torch.cuda.OutOfMemoryError: CUDA out of memory.
on an AMD GPU on Windows.Cause: AMD GPU support on Windows is very experimental. It is implemented via DirectML, which has significant limitations.Solution: If no other SDXL software can run on this device on Windows, there is little that can be done. If you can run SDXL on this device in any other software, please open a GitHub issue immediately so the team can investigate.
AMD support on Linux via ROCm is slightly better than Windows via DirectML. Consider switching to Linux if AMD GPU support is critical for you.
torch.cuda.OutOfMemoryError: CUDA out of memory.
on an AMD GPU on Linux using ROCm.Cause: AMD Linux support via ROCm is still experimental, though better than the Windows/DirectML path.Solution: If you can run SDXL on this device in any other software, open a GitHub issue immediately. If no other software works either, there is limited help available at this time. See the minimal requirements table.
AssertionError: Torch not compiled with CUDA enabled
Cause: You installed a CPU-only version of PyTorch, or followed an incorrect third-party tutorial that installed the wrong torch package.Solution: Follow the official Fooocus installation guide exactly. Do not trust other tutorials on the internet.
error: subprocess-exited-with-error
during pip install -r requirements_versions.txt.Cause: Wrong Python version, or not following the official install guide.Solution: Use Python 3.10 exactly. Other Python versions (3.11, 3.12, etc.) are not guaranteed to work. Follow the official installation guide.
requests.exceptions.SSLError: HTTPSConnectionPool ... SSL: CERTIFICATE_VERIFY_FAILED
Cause: Usually caused by a VPN, corporate proxy, or regional network filtering interfering with HTTPS certificate validation.Solution:
  • Try turning off your VPN and launching Fooocus again.
  • If the problem persists, download the required model files manually. The console prints the download URL and target path for each model when a download is triggered.
RuntimeError: CUDA error: device-side assert triggered
CUDA kernel errors might be asynchronously reported at some other API call
Cause: Usually a driver or CUDA version compatibility issue.Solution: Work through these steps in order:
1

Verify you are using the official release

Download Fooocus only from the official releases page. Some forks are more prone to this error.
2

Upgrade your Nvidia driver

Update to the latest Nvidia driver. The version should be in the 53X series (e.g., 536, 537). Versions in the 3XX or 4XX series are outdated.
3

Try the CUDA 11 + xFormers environment (Windows only)

If upgrading the driver does not help, the issue may be with CUDA 12. Switch to the provided CUDA 11 + xFormers environment:
  1. Back up and delete your python_embeded folder (located next to run.bat).
  2. Download previous_old_xformers_env.7z from the Fooocus releases page.
  3. Decompress it and place the extracted python_embeded folder next to run.bat.
  4. Launch Fooocus normally.
Do not install CUDA manually or modify the Python environment yourself. Only use the provided python_embeded archives.
4

Open an issue

If none of the above resolves the error, open a GitHub issue with your GPU model, driver version, OS, and full traceback.
RuntimeError: Found no NVIDIA driver on your system.
Cause: The Nvidia driver is missing, outdated, or not properly installed.Solution:
Fooocus fails to start or errors on load with a message indicating the Nvidia driver is too old.Cause: The installed Nvidia driver version is too old to support the required CUDA features.Solution: Upgrade to the latest Nvidia driver from the Nvidia driver download page.
UserWarning: The operator 'aten::std_mean.correction' is not currently supported on the DML backend
Cause: A known limitation of the DirectML backend used for AMD GPU support on Windows.Solution: This is a warning only — it is safe to ignore. It does not affect generation quality or correctness.
Fooocus runs but generates images extremely slowly on Apple Silicon (M1/M2) or Intel Mac.Solution:
  • Add --disable-offload-from-vram to speed up model loading and unloading between generations: 
    python entry_with_update.py --disable-offload-from-vram
  • Be aware that Mac support in Fooocus is experimental. For a more optimized Mac experience, consider dedicated Mac applications such as Diffusionbee or Draw Things, which are built specifically for Apple hardware.

​
System Swap

Many of the errors above are caused by the system running out of virtual memory (swap space). Fooocus requires your system to have at least 40 GB of free disk space so the OS can create a sufficiently large swap / page file.
If your swap is stored on an HDD, model loading will be significantly slower. Use an SSD for swap if at all possible.

​
Windows

Windows 10 and 11 manage virtual memory automatically. The most important thing you need to do is ensure you have at least 40 GB of free space on each disk drive. Windows will use that space for automatic page file management. If you have manually disabled automatic page file management — or if you obtained Windows from an unofficial provider that altered these defaults — re-enable automatic management:
1

Open System Properties

Press Win + R, type sysdm.cpl, and press Enter. Navigate to the Advanced tab, then click Settings under Performance.
2

Open Virtual Memory settings

In the Performance Options window, go to the Advanced tab and click Change under Virtual Memory.
3

Enable automatic management

Check Automatically manage paging file size for all drives at the top of the dialog.
4

Apply and restart

Click OK through all dialogs. Restart your computer — changes to the page file only take effect after a reboot.
After changing system swap settings you must restart your computer for the changes to take effect.

​
Linux and macOS

Follow your distribution or OS provider’s official documentation for configuring swap space:

Build docs developers (and LLMs) love

Get started for freeTalk to us