Run Fooocus with Docker or Docker Compose on Linux

The official Fooocus container image is built on NVIDIA CUDA 12.4 and PyTorch 2.1, providing a reproducible, isolated runtime that works on any Linux host with an NVIDIA GPU and the NVIDIA Container Toolkit installed. Models and outputs are stored in a named Docker volume (fooocus-data) so they persist across container restarts and image updates. Podman is also supported for rootless deployments.

Prerequisites

A host machine with proprietary NVIDIA drivers installed
Docker and Docker Compose, or Podman
NVIDIA Container Toolkit (for GPU pass-through with Docker)

Docker on Mac and Windows does not support the MPS backend (Apple Silicon) or expose GPUs in the same way as Linux. The NVIDIA CUDA image requires a Linux host. For Mac, use the native Mac installation guide instead.

Running Fooocus

Docker Compose
Docker
Podman

Docker Compose is the recommended method. It handles GPU reservations, volume creation, and environment variables automatically.1. Clone the repository:

git clone https://github.com/lllyasviel/Fooocus.git
cd Fooocus

2. Start the container:

docker compose up

To run detached in the background:

docker compose up -d

Then follow the logs:

docker compose logs -f

When you see Use the app with http://0.0.0.0:7865/ in the console output, open that URL in your browser.Updating the container:When running docker compose up continuously, the container is not updated automatically. To rebuild with the latest Fooocus version:

git pull
docker compose build --no-cache
docker compose up

Run the pre-built image directly with docker run, passing GPU access and all required environment variables:

docker run -p 7865:7865 -v fooocus-data:/content/data -it \
--gpus all \
-e CMDARGS=--listen \
-e DATADIR=/content/data \
-e config_path=/content/data/config.txt \
-e config_example_path=/content/data/config_modification_tutorial.txt \
-e path_checkpoints=/content/data/models/checkpoints/ \
-e path_loras=/content/data/models/loras/ \
-e path_embeddings=/content/data/models/embeddings/ \
-e path_vae_approx=/content/data/models/vae_approx/ \
-e path_upscale_models=/content/data/models/upscale_models/ \
-e path_inpaint=/content/data/models/inpaint/ \
-e path_controlnet=/content/data/models/controlnet/ \
-e path_clip_vision=/content/data/models/clip_vision/ \
-e path_fooocus_expansion=/content/data/models/prompt_expansion/fooocus_expansion/ \
-e path_outputs=/content/app/outputs/ \
ghcr.io/lllyasviel/fooocus

When you see Use the app with http://0.0.0.0:7865/ in the console output, open http://localhost:7865 in your browser.

Podman provides a rootless alternative with equivalent functionality. Use --security-opt and --cap-drop flags instead of --gpus:

podman run -p 7865:7865 -v fooocus-data:/content/data -it \
--security-opt=no-new-privileges --cap-drop=ALL --security-opt label=type:nvidia_container_t --device=nvidia.com/gpu=all \
-e CMDARGS=--listen \
-e DATADIR=/content/data \
-e config_path=/content/data/config.txt \
-e config_example_path=/content/data/config_modification_tutorial.txt \
-e path_checkpoints=/content/data/models/checkpoints/ \
-e path_loras=/content/data/models/loras/ \
-e path_embeddings=/content/data/models/embeddings/ \
-e path_vae_approx=/content/data/models/vae_approx/ \
-e path_upscale_models=/content/data/models/upscale_models/ \
-e path_inpaint=/content/data/models/inpaint/ \
-e path_controlnet=/content/data/models/controlnet/ \
-e path_clip_vision=/content/data/models/clip_vision/ \
-e path_fooocus_expansion=/content/data/models/prompt_expansion/fooocus_expansion/ \
-e path_outputs=/content/app/outputs/ \
ghcr.io/lllyasviel/fooocus

The fooocus-data volume is stored at ~/.local/share/containers/storage/volumes/ when using Podman.

Environment Variables

You can configure Fooocus’s runtime behaviour and model paths through environment variables. The values set here take higher priority than anything written in config.txt, and they are saved to config_modification_tutorial.txt inside the container.

Container-specific variables

Variable	Description
`DATADIR`	Path to the persistent data directory (default: `/content/data`)
`CMDARGS`	Arguments passed to the Fooocus launcher (e.g. `--listen`, `--preset anime`)
`HF_MIRROR`	Hugging Face mirror domain for model downloads (useful in regions with restricted access)

Config path variables

Variable	Description
`config_path`	Location of `config.txt`
`config_example_path`	Location of `config_modification_tutorial.txt`

Model path variables

Variable	Default value
`path_checkpoints`	`/content/data/models/checkpoints/`
`path_loras`	`/content/data/models/loras/`
`path_embeddings`	`/content/data/models/embeddings/`
`path_vae_approx`	`/content/data/models/vae_approx/`
`path_upscale_models`	`/content/data/models/upscale_models/`
`path_inpaint`	`/content/data/models/inpaint/`
`path_controlnet`	`/content/data/models/controlnet/`
`path_clip_vision`	`/content/data/models/clip_vision/`
`path_fooocus_expansion`	`/content/data/models/prompt_expansion/fooocus_expansion/`
`path_outputs`	`/content/app/outputs/`

Container Path Reference

Path	Details
`/content/app`	Application directory — Fooocus source code lives here
`/content/app/models.org`	Original bundled model stubs. On each boot, files are copied to `/content/app/models` (which is symlinked to `/content/data/models`). Existing files are not overwritten.
`/content/data`	Persistent volume mount point
`/content/data/models`	Symlinked to `/content/app/models` — all model files live here
`/content/data/outputs`	Symlinked to `/content/app/outputs` — all generated images live here

Importing Models and Outputs

If you have existing models or output images you want to bring into the container, uncomment the bind-mount lines in docker-compose.yml:

volumes:
  - fooocus-data:/content/data
  - ./models:/import/models    # Once you import files, you don't need to mount again.
  - ./outputs:/import/outputs  # Once you import files, you don't need to mount again.

On the next container start, files from ./models and ./outputs on the host will be copied into /content/data/models and /content/data/outputs inside the volume. Because the volume is persistent, you can remove the bind mounts after the first import — your files remain available on every subsequent run.

Building the Image Locally

If you want to build the container image from source rather than pulling from ghcr.io:

Docker
Podman

docker build . -t fooocus

podman build . -t fooocus

Then replace ghcr.io/lllyasviel/fooocus with fooocus in your run command or update the image: line in docker-compose.yml.

Notes

Keep path_outputs under /content/app — if you move path_outputs outside of /content/app, the in-browser history log will not be able to display your generated images. The default value /content/app/outputs/ is safe to use as-is.

Volume performance on Mac and Windows — Docker on Mac and Windows can exhibit slow volume access when using bind mounts. Use named volumes (the default fooocus-data volume) rather than bind mounts to avoid performance issues. See the Docker volumes documentation for details.

MPS not supported in Docker — The Metal Performance Shaders (MPS) backend for Apple Silicon (M1/M2) is not supported inside Docker containers. Mac users must follow the native Mac installation guide to run Fooocus with GPU acceleration.

Get Started

Installation Guides

Core Features

Advanced Usage

Deployment & Operations

Run Fooocus with Docker or Docker Compose on Linux

Prerequisites

Running Fooocus

Environment Variables

Container-specific variables

Config path variables

Model path variables

Container Path Reference

Importing Models and Outputs

Building the Image Locally

Notes

Build docs developers (and LLMs) love

Get Started

Installation Guides

Core Features

Advanced Usage

Deployment & Operations

Documentation Index

​Prerequisites

​Running Fooocus

​Environment Variables

​Container-specific variables

​Config path variables

​Model path variables

​Container Path Reference

​Importing Models and Outputs

​Building the Image Locally

​Notes

Build docs developers (and LLMs) love

Prerequisites

Running Fooocus

Environment Variables

Container-specific variables

Config path variables

Model path variables

Container Path Reference

Importing Models and Outputs

Building the Image Locally

Notes