FooocusRunner is a command line utility written in python to automate and batch process the AI image generation of the tool "Fooocus" by Illyasviel. Prompts are stored together with their metadata (e.g. used models, used styles, used face swaps etc.) in yaml files. FooocusRunner then reads these prompt "job" files and lets Fooocus generate the images randomly. After each generation, the generated image is hardlinked into specific subfolders for better organization.
Example yaml prompt file:
beautiful young woman
beautiful face, beauty, lovely
smiling, happy
black latex catsuit
long blonde hair
classic photographic portrait, photo shoot, modeling,
studio red paper background
---
watermark, text, logo
---
models:
- model: lustifySDXLNSFW_endgame.safetensors
refiner_model: juggernaut_reborn.safetensors
refiner_switch_at: 0.69
performance: Speed
guidance: 7
aspect_ratios: ["19:13"]
styles: ["Photo Glamour"]
Have a look at the example folder of this repo to see a few yaml job files.
Since your prompts are yaml text files, they can be organized and version controlled with git.
- Fooocus 2.5.5 must run smoothly
- Linux (FooocusRunner was written on Ubuntu, not tested on nor ported to Windows)
- Lots of RAM if you plan to switch models in a run (Fooocus will terminate when there is only like 16 GB RAM (not VRAM) and you switch 8 GB Models a few times). FooocusRunner works good on 64 GB RAM and more.
https://github.com/lllyasviel/Fooocus
Fooocus version: 2.5.5
Make sure it works, so you can generate images in the browser as intended.
sudo apt install python3-tk
python3 -m venv fooocus_runner_env
open environment:
source fooocus_runner_env/bin/activate
within the venv:
pip install -r requirements_versions.txt
pip install .
Edit the config file fooocus_runner_config.yaml in the root dir and set it to Fooocus' outputs folder (where fooocus puts the generated images):
fooocus_output_dir: "/path/to/fooocus/outputs"
Make sure that Fooocus is fully started and ready (browser interface is open) and it is idle (not generating anything!)
If not in it, switch to the venv:
source fooocus_runner_env/bin/activate
Run the example prompts for relaxed cats and/or for beautiful women:
fooocusrunner examples/prompts/ examples/cats.joblist.yaml
fooocusrunner examples/prompts/ examples/women.joblist.yaml
The examples should be Safe For Work but with AI everything can happen, so handle the run with care!
Fooocus should now run and generate images into the in Fooocus' config specified output folder.
To stop FooocusRunner, press "OK" in the small dialog box that opened.
Start Fooocus, wait for it to be fully loaded and ready.
Switch on venv:
source fooocus_runner_env/bin/activate
Start FooocusRunner:
fooocusrunner [dir_of_prompt_files] [job_list_yaml_file]
FooocusRunner expects all files to be present in one directory structure (perfect for git!). The name of the subdirs is irrelevant for FooocusRunner and only for your own file organization, so every filename needs to be unique to work.
FooocusRunner handles the following files:
| filetype | contents |
|---|---|
.yaml |
a job file, contains a prompt and its metadata |
.joblist.yaml |
a list of job filenames to be generated in a run |
.rule.yaml |
an expansion rule |
.png, .jpeg, ... |
pictures for face swap |
Since the .yaml files are standard .yaml files, you can edit them in your favorite editor with syntax highlighting, like VSC.
Job files contain your prompts. Either as simple text prompts, text prompts with settings or even rules to create a text prompt randomly.
Basic outline of a job file is as follows:
[Positive prompt]
---
[Negative prompt*]
---
[Metadata Settings*]
(*) optional, if not present, then also omit the three dashes "---"
Negative prompt and Settings are both optional. So your most simple prompt can be only the text you enter in the prompt text area of Fooocus!
Since these are standard yaml files, you can comment out whole lines with #
Note that it is irrelevant what you enter or set in the Fooocus browser interface (e.g. base model, guidance), since FooocusRunner connects "in parallel" to the browser interface with the Fooocus "Server". When using FooocusRunner, you have to use the Metadata Settings and the config file of FooocusRunner to change values!
Have a look at the example prompt file garden_cat.yaml:
cat running in a beautiful garden
sunday morning, warm light
See the example garden_cat_no_brown_cats.yaml, which omits brown cats. See the negative prompt divided by three dashes "---":
cat running in a beautiful garden
sunday morning, warm light
---
brown cat
See the example relaxed_cat.yaml, the metadata is appended after another three dashed line "---":
cat relaxing on a sofa
sunday morning, warm light,
villa living room
---
text, logo, watermark
---
models:
- model: juggernautXL_v8Rundiffusion.safetensors
performance: Speed
guidance: 7
aspect_ratios: ["19:13"]
Note that you can also leave out the negative prompt like this:
cat relaxing on a sofa
sunday morning, warm light,
villa living room
---
models:
- model: juggernautXL_v8Rundiffusion.safetensors
performance: Speed
guidance: 7
aspect_ratios: ["19:13"]
Lets have a look at all metadata settings:
Examples:
Only base model:
models:
- model: donutsdeliverymixV4_v41.safetensors
performance: Quality
Base model and refiner, guidance higher:
models:
- model: donutsdeliverymixV4_v41.safetensors
refiner_model: juggernaut_reborn.safetensors
refiner_switch_at: 0.69
performance: Quality
guidance: 7
More models per prompt:
models:
- model: lustifySDXLNSFW_endgame.safetensors
refiner_model: juggernaut_reborn.safetensors
refiner_switch_at: 0.69
performance: Speed
guidance: 7
- model: donutsdeliverymixV4_v41.safetensors
refiner_model: juggernaut_reborn.safetensors
refiner_switch_at: 0.69
performance: Speed
guidance: 7
List the styles of Fooocus you want to see mixed in. Copy the names directly from the web interface of Fooocus:
One style:
styles: ["Photo Glamour"]
More styles:
styles: ["MRE Cinematic Dynamic","Futuristic Cyberpunk Cityscape"]
Rating sets the probability of a job being selected randomly. Think of 0 to 5 stars you can give to a job. If rating is not set, it is a little less than 3 stars. 0 stars will be selected 5% of times, 5 stars 100%.
Example:
rating: 4 # I like it!
FooocusRunner only selects photography landscape, portrait or 1:1 as aspect ratios randomly. You can force one of these by setting aspect_ratio:
Force portrait:
aspect_ratios: ["13:19"]
Force landscape:
aspect_ratios: ["19:13"]
Place image files with unique names within the prompt folder directory structure. You then can reference them by name and list 1 to 4 images like this (Example for 2 images):
faceswap:
- image: "attractive_person_look_1.png"
stop_at: 0.9
weight: 0.75
- image: "attractive_person_look_2.png"
stop_at: 0.9
weight: 0.75
This will probably be changed in a future version, since PyraCanny and CPDS will be integrated.
You can include special expansion rules into the prompts, which load prompt parts from other files. These can be nested (loaded parts will load other parts). The .rule.yaml files need unique filenames which are then referenced as $..$ in the prompt text.
If a .rule.yaml file is referenced, a random line of this file is selected and integrated into the prompt. If the line contains another rule file, this is then looked up in the same way.
Reserved rule names:
| Reserved rule name | effect |
|---|---|
$br$ |
inserts linebreak into prompt, as you cannot use a normal linebreak in a rule file, since every line is a separate entry |
$empty$ |
results in an empty insert like "", useful for empty lines in a rule file |
Example:
woman
smiling, happy
$color$ $dresses$ $shoes$
$hair$
classic photo shoot, modeling,
The prompt will be expanded: For $color$ the file color.rule.yaml is looked up within the prompt directory. It looks like this:
red
blue
white
purple
black
green
golden
yellow
pink
grey
so one of these colors is randomly inserted:
smiling, happy
green $dresses$ $shoes$
$hair$
classic photo shoot, modeling,
And so forth...
For more ideas, have a look at the example files in examples/prompts/rules_example with the job mixed_dresses.yaml.
You can easily integrate wildcard collections like https://github.com/eddyizm/YetAnotherWildcardCollection
To ignore directories and .yaml files during parsing, use x_ as a prefix in the name.
Example:
The dir x_bad_ones and its content will not be parsed.
Job-List files named .joblist.yaml contain the names of the job files you want to be generated.
Example:
- relaxed_cat.yaml
- pool_glamour_cats.yaml
# - garden_cat.yaml
- garden_cat_no_brown_cats.yaml
Note that you can use # to comment out prompts you do not want to be generated
If you want to generate a joblist with all prompt files of a directory automatically, just run FooocusRunner with a new non existing filename for a joblist:
fooocusrunner [dir_of_prompt_files] [new_job_list_yaml_file]
where the new_job_list_yaml_file is currently not an existing file and will be created by FooocusRunner.
You can specify per job entry, how many pictures should be generated as a maximum and what the chance (in percent) of the job to be selected is (this overrides the "rating" setting):
- modelpose_studio.yaml
- modelpose_studio_latex.yaml:
chance: 30
max: 10
This is way too experimental. If you specify a max for every job, FooocusRunner will run indefinitely doing nothing after completion of all jobs.
Sets the number of images to be generated per prompt that FooocusRunner selects randomly. Default is 1. Rules are expanded and then the number of images are produced from the same expanded prompt. Note that if you press OK to stop FooocusRunner, this number of images will first be finished before FooocusRunner exits.
This setting is useful if you have hundreds of prompts for a run and want to have at least e.g. 10 images per selected prompt and not 200 prompts with only 1 to 2 images.
Starts FooocusRunner and exits when a connection to Fooocus is about to be made. Useful together with -v (verbose), so that you can check everything is as expected before starting any generation.
Show more info (e.g. which yaml or face swap files are loaded etc)
Overrides generations_per_full_run config setting (see config file below)
For this you have to have nvidia-smi installed. FooocusRunner will then try to remain under a specific GPU temperature by waiting for a cool down until handling the next job.
The config file is searched first as a dot file in your home dir ~/.fooocus_runner_config.yaml, then as fooocus_runner_config.yaml in the root dir of the repo.
For job files without base model and refiner you can specify the default models in the config file:
default_base_model: "juggernautXL_v8Rundiffusion.safetensors"
default_refiner: ""
Fooocus has a defined number of images per model it will generate. After that it will switch to the next model / refiner combination.
If your GPU is faster than mine and you experience a switch too often, set this parameter to a higher value (like 240,500,800, etc) in the config file:
generations_per_full_run: 120
If you want png instead of jpg, change the entry output_format in the config file to png.
The following keywords in the prompt metadata will probably be used in a future version of FooocusRunner, e.g. for filtering jobs and for a gui that presents all jobs etc.
tags: [latex, nn, outside]
comment: "My personal favorite!"
reference: 2025-07-02_14-00-11_1234.jpeg
- Handle loras (you can still add them as text into the prompt)
First initial github release