Fooocus Documentation

System Requirements

Installation

Windows

Windows installation is straightforward with the embedded Python package:

1. Download the Windows package
2. Extract to desired location
3. Run run.bat

See Getting Started for detailed instructions.

macOS

macOS installation requires Python:

# Install dependencies
pip install -r requirements.txt

# Run Fooocus
python entry_with_update.py

Linux

Linux installation:

# Install system dependencies
sudo apt-get install python3 python3-pip

# Install Python dependencies
pip install -r requirements.txt

# Run Fooocus
python entry_with_update.py

Command-Line Options

Fooocus supports various command-line options for customization:

Configuration Files

Fooocus uses configuration files for customization. The main config file is config.txt.

Config File Structure

# Model paths
base_model_path = models/checkpoints/
lora_path = models/loras/

# Default parameters
default_steps = 30
default_cfg_scale = 7.0

# Output settings
output_path = outputs/
output_format = png

Common Configuration Options

• Model Paths: Customize where models are stored
• Default Parameters: Set default generation settings
• Output Settings: Configure output directory and format
• Performance: Adjust memory and speed settings

See Customization Guide for detailed configuration options.

Directory Structure

Understanding Fooocus directory structure:

Fooocus/
├── models/
│   ├── checkpoints/      # Base models (SDXL)
│   ├── loras/            # LoRA files
│   ├── vae/              # VAE models
│   └── upscale/          # Upscaling models
├── wildcards/            # Wildcard text files
├── outputs/              # Generated images
├── config.txt            # Configuration file
├── entry_with_update.py  # Main entry point
└── requirements.txt      # Python dependencies

Model Management

Supported Model Formats

• SDXL base models (.safetensors, .ckpt)
• LoRA models (.safetensors, .ckpt)
• VAE models (.safetensors, .ckpt)
• Upscaling models

Model Download

Fooocus automatically downloads required models on first launch. You can also:

• Manually download models and place in appropriate directories
• Use --hf-mirror for alternative download sources
• Configure custom model paths in config files

Model Sources

• Hugging Face - Official model repository
• Civitai - Community models and LoRAs

Wildcards Documentation

Wildcards are defined in text files in the wildcards directory.

Wildcard File Format

# This is a comment
option1
option2
option3

Using Wildcards

Reference wildcards in prompts: __wildcard_name__

Example: wildcards/color.txt contains:

red
blue
green

Use in prompt: A __color__ flower

See Advanced Features for more wildcard techniques.

API Reference

Fooocus provides a web API for programmatic access:

Endpoints

• /api/generate - Generate images
• /api/models - List available models
• /api/status - Get system status

Generate Endpoint

POST /api/generate
{
  "prompt": "your prompt here",
  "negative_prompt": "negative elements",
  "steps": 30,
  "cfg_scale": 7.0,
  "seed": -1
}

Internationalization

Fooocus supports multiple languages through JSON translation files.

Translation File Format

Translation files are located in translations/ directory:

translations/
├── en.json    # English
├── es.json    # Spanish
├── fr.json    # French
└── ...

Creating Translations

Translation files use JSON format:

{
  "ui.prompt": "Prompt",
  "ui.generate": "Generate",
  "ui.settings": "Settings"
}

Using Translations

Set language via command line: --language es

Or configure in config.txt: language = es

Troubleshooting

Common Issues

Model Download Fails

• Check internet connection
• Verify disk space
• Try --hf-mirror flag
• Manually download models

Out of Memory

• Use --always-low-vram
• Reduce image resolution
• Close other applications
• Use CPU mode if GPU insufficient

Slow Performance

• Ensure GPU acceleration enabled
• Check CUDA installation
• Use appropriate performance preset
• Optimize model loading

Performance Tuning

Memory Optimization

• Use low VRAM mode for limited GPU memory
• Enable model offloading when idle
• Adjust attention mechanism
• Use CPU offloading for very limited VRAM

Speed Optimization

• Choose faster sampling methods
• Optimize step counts
• Enable async CUDA allocation
• Use batch processing efficiently

Related Resources