WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 9 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Fooocus is a Stable Diffusion XL-based image generation application built on Gradio that focuses on prompt-centric image synthesis with minimal manual parameter tuning. It provides a simplified, offline, open-source alternative to Midjourney by automatically handling complex configuration and model loading—users input prompts and reference images, and the system generates high-quality outputs without requiring deep knowledge of diffusion model hyperparameters. Monolithic application structure: entry_with_update.py and build_launcher.py are orchestration scripts; args_manager.py handles configuration; experiments_*.py files (expansion, face, interrogate, mask_generation) contain specialized pipelines; extras/ subdirectories hold pre-configured model weights and configs (BLIP for captioning, GroundingDINO for grounding); Docker-based deployment via Dockerfile and docker-compose.yml.

AI/ML practitioners and end-users seeking accessible text-to-image generation without cloud dependencies or complex parameter engineering. Primary audience includes researchers experimenting with SDXL variants, developers integrating local image generation into applications, and users preferring offline-first workflows with deterministic reproducibility.

Production-ready but in limited long-term support (LTS) mode. The project is mature and stable on SDXL, with critical infrastructure in place (Docker support, GitHub Actions CI/CD in .github/workflows/), but is explicitly not adding new features—only bug fixes. This is a deliberate design choice, not abandonment; the maintainers have shifted focus to WebUI Forge for newer architectures.

Low risk for current use, high risk for future feature expansion. The LTS-only commitment means no planned updates to newer models (Flux, etc.) and reliance on a single core architecture (SDXL). Single-maintainer pattern with lllyasviel as primary author increases maintenance risk if he becomes unavailable. Heavy dependency on external model repos (BLIP, GroundingDINO in extras/) could break if those projects change incompatibly.

The project is in maintenance mode with bug-fix-only commits. Based on the 'Project Status' README section prominently stating LTS with no planned architecture migration, active development has ceased. The focus has shifted to alternative projects (WebUI Forge, ComfyUI/SwarmUI forks). However, security and compatibility patches are ongoing.

Check README for instructions.

Daily commands: After install: python entry_with_update.py. This auto-downloads SDXL weights to ~/.cache/ and launches the Gradio server (default http://127.0.0.1:7860). For headless: set --listen 0.0.0.0 (see args_manager.py). Docker: docker-compose up (watches docker.md for port mappings, usually 7860). Windows: run build_launcher.py for bundled Python + dependencies.

• launch.py — Primary entry point for the Fooocus application; initializes the Gradio UI and orchestrates the image generation pipeline.
• args_manager.py — Centralized argument and configuration management; controls all CLI flags, environment settings, and runtime parameters used across the codebase.
• ldm_patched/contrib/external.py — Core extension mechanism for custom nodes and external modules; defines the plugin architecture for adding new generation capabilities.
• extras/interrogate.py — Image interrogation and caption generation using BLIP model; essential for reverse-prompt inference and understanding generated images.
• extras/preprocessors.py — Input preprocessing pipeline including ControlNet and auxiliary image processing; normalizes and prepares images for model inference.
• fooocus_version.py — Version tracking and compatibility metadata; critical for update mechanisms and feature gating across the application.
• environment.yaml — Conda dependency specification defining all core ML libraries, PyTorch versions, and system requirements for reproducible installation.

Add a Custom Node/External Module

1. Create a new Python module in ldm_patched/contrib/ following the naming convention external_[feature].py (ldm_patched/contrib/external.py)
2. Implement node class inheriting from NODE_CLASS_MAPPINGS and define INPUT_TYPES, RETURN_TYPES, FUNCTION signature (ldm_patched/contrib/external_custom_sampler.py)
3. Register node in NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS dictionaries at module end (ldm_patched/contrib/external.py)
4. Add unit tests or experiments in experiments_[feature].py to validate the new node (experiments_expansion.py)

Add a New Image Preprocessor

1. Define preprocessor function in extras/preprocessors.py with input validation and numpy/PIL array handling (extras/preprocessors.py)
2. Register preprocessor in the PREPROCESSOR_REGISTRY or similar mapping used by the main pipeline (extras/preprocessors.py)
3. Update the UI form generation in launch.py to expose the preprocessor as a selectable option in Gradio (launch.py)
4. Test with experiments_expansion.py or create a test image flow to verify preprocessing output (experiments_expansion.py)

Customize Configuration & CLI Arguments

1. Add argument definition with default value, type, and help text in args_manager.py (args_manager.py)
2. Reference the parsed argument via the global config object throughout the codebase (e.g., config.my_arg) (launch.py)
3. Update environment.yaml if new dependencies are required for the feature (environment.yaml)
4. Document the new argument in development.md for contributor reference (development.md)

Add a New UI Component or Tab

1. Create a Gradio interface block (e.g., gr.Tab, gr.Group) in launch.py with input/output components (launch.py)
2. Define a backend handler function that processes inputs and returns results (may call ldm_patched or extras modules) (launch.py)
3. Connect UI components to handlers using Gradio's .click(), .change() or .submit() event listeners (javascript/script.js)
4. Add custom CSS styling in css/style.css to match the existing Fooocus design language (css/style.css)

• Stable Diffusion XL (SDXL) — State-of-the-art open-source text-to-image model; provides high-quality output with minimal manual tuning required
• Gradio — Rapid UI prototyping with zero-code component binding; enables quick iteration on frontend without separate API/frontend development
• PyTorch + CUDA — Industry standard for deep learning inference; enables GPU acceleration on consumer-grade NVIDIA GPUs (4GB+ VRAM)
• Conda + Docker — Reproducible environment isolation; simplifies multi-platform deployment (Windows, macOS, Linux) with <3 clicks to first image
• BLIP + GroundingDINO — Lightweight models for image understanding and semantic grounding; enable reverse-prompt inference and object detection without heavy dependencies

• Monolithic single-process architecture instead of distributed microservices

  • Why: Simplicity and fast time-to-first-image; avoids inter-process communication overhead on consumer hardware
  • Consequence: Limited horizontal scalability; not suitable for high-concurrency cloud deployments; one user blocks others during generation

• In-memory model caching without persistent state management

  • Why: Reduces latency on repeated generations; avoids expensive model reload from disk
  • Consequence: High RAM footprint (~8-12GB for base SDXL); no multi-GPU or distributed inference support

• Gradio-based UI instead of custom React/Vue frontend

  • Why: Rapid prototyping and maintenance burden reduction; Python developers can own full stack
  • Consequence: Limited customization of advanced UX patterns; performance bottlenecks in real-time features (e.g., live prompt preview)

• Offline-first with no cloud integration or authentication

  • Why: User privacy and autonomous operation; no dependency on external services
  • Consequence: Cannot leverage distributed generation, cloud models, or cross-device sync; manual management of model updates

• Manual prompt engineering focus instead of automatic optimization

  • Why: Aligns
  • Consequence: undefined

1. Model auto-download: entry_with_update.py triggers multi-GB downloads on first run (SDXL base + VAE + embeddings); network must be stable and ~/.cache/ must have ~30GB free. 2) GPU memory optimization flags in args_manager.py (--lowvram, --normalvram, --highvram) are critical; defaults assume 4GB NVIDIA but CPU inference is unsupported—AMD/Intel will fail silently. 3) BLIP and GroundingDINO extras require their own model downloads (see extras/BLIP/configs/ and extras/GroundingDINO/config/); missing these breaks interrogate and mask features. 4) Python 3.8-3.10 required (3.11+ may have torch compatibility issues). 5) Gradio version pinning in environment.yaml is strict; deviating breaks UI serialization.

• Latent Diffusion — SDXL operates in a learned latent space (via VAE), not pixel space; understanding this explains why inference is fast and why the VAE choice matters for quality
• Classifier-Free Guidance (CFG) — CFG scale parameter in args_manager.py controls the trade-off between prompt adherence and image diversity; core to Fooocus's 'follow the prompt' behavior
• LoRA (Low-Rank Adaptation) — Fooocus supports LoRA fine-tuning for style/subject injection; understanding LoRA weights and merging is essential for advanced customization
• Vision Transformer (ViT) + BLIP — extras/BLIP/models/vit.py and blip.py implement image-to-text; used in interrogate feature to reverse-engineer prompts from images
• Grounding DINO (Detection with Language) — extras/GroundingDINO enables text-conditioned object detection; powers mask generation and spatial control features
• Prompt Weighting Syntax — Fooocus extends SDXL's prompt syntax (e.g., '(cat:1.5) on table') to control per-token emphasis dynamically; experiments_expansion.py parses and applies these weights
• Model Quantization & Memory Optimization — args_manager.py's --lowvram flag triggers int8 quantization and sequential offloading to CPU; critical for sub-6GB GPU operation

• lllyasviel/stable-diffusion-webui-forge — Official successor from same author; supports Flux and newer architectures; recommended migration path for users needing beyond-SDXL capabilities
• comfyanonymous/ComfyUI — Node-graph-based diffusion orchestration; allows fine-grained control and custom workflows that Fooocus intentionally abstracts away
• AUTOMATIC1111/stable-diffusion-webui — Original SDXL WebUI; more feature-rich but requires heavy parameter tuning; Fooocus simplified this UX philosophy
• gradio-app/gradio — Underlying web framework; Fooocus UI is built entirely on Gradio components; understanding Gradio internals helps troubleshoot interface issues
• openai/CLIP — Text-image encoder that powers SDXL's conditioning pipeline; understanding CLIP tokenization and embedding is key to prompt behavior

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for extras/expansion.py and experiments_expansion.py

The repo has prompt expansion functionality (extras/expansion.py) and an experiments file (experiments_expansion.py) but no visible test coverage. Given that prompt processing is core to Fooocus's value proposition ('focus on prompting'), adding tests would prevent regressions and document expected behavior. This is critical for a feature users directly interact with.

• [ ] Create tests/test_expansion.py with test cases for prompt expansion logic in extras/expansion.py
• [ ] Add tests for edge cases: empty prompts, very long prompts, special characters, multi-language inputs
• [ ] Reference experiments_expansion.py to understand the expansion algorithm and test those specific behaviors
• [ ] Integrate test execution into .github/workflows (note: build_container.yml exists but likely doesn't run unit tests)
• [ ] Add pytest to environment.yaml dependencies

Add unit tests for extras/facexlib/ face detection and parsing modules

The face detection (extras/facexlib/detection/) and parsing (extras/facexlib/parsing/) modules have complex neural network logic but no visible test suite. These features are used in experiments_face.py and affect image quality. Tests would catch model loading failures, tensor shape mismatches, and preprocessing issues early.

• [ ] Create tests/test_face_detection.py testing extras/facexlib/detection/retinaface.py with sample images
• [ ] Create tests/test_face_parsing.py for extras/facexlib/parsing/ modules (bisenet.py, parsenet.py)
• [ ] Add mock/fixture image files or use small test images to avoid large dependencies
• [ ] Test error handling: missing models, corrupt input images, edge cases (multiple faces, no faces, extreme angles)
• [ ] Add tests to CI pipeline in .github/workflows/

Add GitHub Actions workflow for testing Docker builds and image interrogation pipeline

The repo has Dockerfile and docker-compose.yml but .github/workflows/build_container.yml appears to only build containers without testing the actual pipeline. experiments_interrogate.py suggests an interrogation feature (likely image-to-prompt using BLIP in extras/BLIP/). A workflow testing end-to-end functionality would catch breaking changes early and validate the Docker setup works as documented in docker.md.

• [ ] Create .github/workflows/test_interrogation.py workflow that runs experiments_interrogate.py with a test image
• [ ] Add workflow step to verify BLIP model loading and inference on CPU (for cost-effective CI)
• [ ] Test Docker image builds: validate Dockerfile builds successfully and that entrypoint.sh works
• [ ] Add workflow step to check that auth-example.json schema is valid (if auth is required)
• [ ] Document expected test outcomes in development.md

• Add unit tests for experiments_expansion.py: the prompt expansion logic lacks test coverage; create tests/test_prompt_expansion.py with fixtures for common prompt patterns (descriptive, style-based, negative prompts) to catch regressions.
• Document GPU memory tier selection in README: args_manager.py has --lowvram, --normalvram, --highvram flags but no guidance on which to choose for 4GB/6GB/8GB/12GB cards; add a troubleshooting.md table matching GPU models to recommended flags.
• Add type hints to args_manager.py: the 600+ line config file has no type annotations; incrementally add from typing import Dict, List, Optional and annotate function signatures to improve IDE support and catch config bugs early.

• High · Unsafe Gradio FRPC Binary Download — Dockerfile, line: RUN curl -fsL -o /usr/local/lib/python3.10/dist-packages/gradio/frpc_linux_amd64_v0.2 https://cdn-media.huggingface.co/frpc-gradio-0.2/frpc_linux_amd64. The Dockerfile downloads an executable binary (frpc_linux_amd64) from an external CDN over HTTPS without verifying its integrity via checksum or signature. This introduces supply chain risk - a compromised CDN or MITM attack could deliver malicious code that runs with user privileges. Fix: Verify the downloaded binary using SHA256 checksums. Example: curl -fsL <url> | sha256sum -c expected_hash.txt && cp to destination. Alternatively, use package managers when available or host the binary in a controlled, scanned repository.
• High · Missing Dependency Pinning in Docker — Dockerfile, lines: RUN pip install --no-cache-dir -r /tmp/requirements_docker.txt && RUN pip install --no-cache-dir xformers==0.0.23 --no-dependencies. The Dockerfile uses pip install without showing full version pinning for dependencies (requirements_docker.txt and requirements_versions.txt are not provided for review). Additionally, xformers==0.0.23 is installed without dependencies (--no-dependencies flag), which may leave the environment in an inconsistent state with unmet transitive dependencies. Fix: Use fully pinned dependency versions with hashes for all packages. Remove --no-dependencies flag or explicitly verify and pin all required transitive dependencies. Use a lock file (e.g., pip-compile output) for reproducible builds.
• High · Exposed Web Application Port Without Authentication — docker-compose.yml, line: ports: - '7865:7865'. The docker-compose.yml exposes port 7865 without any authentication mechanism visible in the provided configuration. Given that this is an image generation service, unauthenticated access allows any network user to consume GPU resources and potentially cause DoS. Fix: Implement authentication via reverse proxy (nginx with auth module), API key validation in the Gradio application, or run behind a VPN. Consider using environment-based access controls and rate limiting.
• Medium · Plaintext Configuration Files in Volume — docker-compose.yml, environment variables path references. The docker-compose.yml mounts /content/data as a persistent volume where config files (config.txt, config_modification_tutorial.txt) are stored. These may contain sensitive information (API keys, model paths, or credentials) in plaintext without encryption. Fix: Encrypt sensitive configuration data. Use secrets management solutions (Docker Secrets, Kubernetes Secrets, or HashiCorp Vault). Never store credentials in config files - use environment variables with secure injection or external secret stores.
• Medium · Weak User Privilege Isolation — Dockerfile, line: COPY --chown=user:user . /c. While the Dockerfile creates a non-root 'user' (good practice), the application copies the entire source code as user:user. If the application has a code execution vulnerability, the attacker gains full access to the /content/app directory and can potentially read/write model files and outputs. Fix: Implement additional runtime security: use AppArmor or SELinux profiles to restrict file access, enable read-only root filesystem where possible, and use seccomp profiles to limit system calls. Consider running sensitive operations in a sandbox.
• Medium · Missing Security Headers in Gradio Configuration — Application entry points (launch.py, entry_with_update.py - not fully provided). Gradio is a web-based UI framework that may be susceptible to XSS if not properly configured with security headers (CSP, X-Frame-Options, etc.). No visible security header configuration in provided files. Fix: Configure Gradio with security headers via middleware or reverse proxy. Set Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff. Review Gradio's built-in security settings.
• Medium · Example Credentials File in Repository — undefined. The file 'auth-example.json' exists in the repository root. If this contains any real credentials or examples that users copy as-is, it could lead to security Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lllyasviel/Fooocus shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lllyasviel/Fooocus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lllyasviel/Fooocus.

What it runs against: a local clone of lllyasviel/Fooocus — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lllyasviel/Fooocus | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 188 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lllyasviel/Fooocus. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lllyasviel/Fooocus.git
#   cd Fooocus
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lllyasviel/Fooocus and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lllyasviel/Fooocus(\\.git)?\\b" \\
  && ok "origin remote is lllyasviel/Fooocus" \\
  || miss "origin remote is not lllyasviel/Fooocus (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "launch.py" \\
  && ok "launch.py" \\
  || miss "missing critical file: launch.py"
test -f "args_manager.py" \\
  && ok "args_manager.py" \\
  || miss "missing critical file: args_manager.py"
test -f "ldm_patched/contrib/external.py" \\
  && ok "ldm_patched/contrib/external.py" \\
  || miss "missing critical file: ldm_patched/contrib/external.py"
test -f "extras/interrogate.py" \\
  && ok "extras/interrogate.py" \\
  || miss "missing critical file: extras/interrogate.py"
test -f "extras/preprocessors.py" \\
  && ok "extras/preprocessors.py" \\
  || miss "missing critical file: extras/preprocessors.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 188 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~158d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lllyasviel/Fooocus"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.