# YAML Config Runtime settings, including the location of files and directories, memory usage, and performance, are managed via the `invokeai.yaml` config file or environment variables. A subset of settings may be set via command-line arguments. Settings sources are used in this order: - CLI args - Environment variables - `invokeai.yaml` settings - Fallback: defaults ### InvokeAI Root Directory On startup, InvokeAI searches for its “root” directory. This is the directory that contains models, images, the database, and so on. It also contains a configuration file called `invokeai.yaml`. - Directory models/ - … - Directory outputs/ - … - Directory databases/ - … - Directory workflow_thumbnails/ - … - Directory style_presets/ - … - Directory nodes/ - … - Directory configs/ - … - invokeai.example.yaml - **invokeai.yaml** InvokeAI searches for the root directory in this order: 1. The `--root ` CLI arg. 2. The environment variable INVOKEAI_ROOT. 3. The directory containing the currently active virtual environment. 4. Fallback: a directory in the current user’s home directory named `invokeai`. ### InvokeAI Configuration File Inside the root directory, we read settings from the `invokeai.yaml` file. It has two sections - one for internal use and one for user settings: ```yaml # Internal metadata - do not edit: schema_version: 4.0.2 # Put user settings here - see https://invoke.ai/configuration/invokeai-yaml/: host: 0.0.0.0 # serve the app on your local network models_dir: D:\invokeai\models # store models on an external drive precision: float16 # always use fp16 precision ``` The settings in this file will override the defaults. You only need to change this file if the default for a particular setting doesn’t work for you. ### Custom Config File Location You can use any config file with the `--config` CLI arg. Pass in the path to the `invokeai.yaml` file you want to use. Note that environment variables will trump any settings in the config file. ### Model Marketplace API Keys Some model marketplaces require an API key to download models. You can provide a URL pattern and appropriate token in your `invokeai.yaml` file to provide that API key. The pattern can be any valid regex (you may need to surround the pattern with quotes): ```yaml remote_api_tokens: # Any URL containing `models.com` will automatically use `your_models_com_token` - url_regex: models.com token: your_models_com_token # Any URL matching this contrived regex will use `some_other_token` - url_regex: '^[a-z]{3}whatever.*\.com$' token: some_other_token ``` The provided token will be added as a `Bearer` token to the network requests to download the model files. As far as we know, this works for all model marketplaces that require authorization. ### Model Hashing Models are hashed during installation, providing a stable identifier for models across all platforms. Hashing is a one-time operation. ```yaml hashing_algorithm: blake3_single # default value ``` You might want to change this setting, depending on your system: - `blake3_single` (default): Single-threaded - best for spinning HDDs, still OK for SSDs - `blake3_multi`: Parallelized, memory-mapped implementation - best for SSDs, terrible for spinning disks - `random`: Skip hashing entirely - fastest but of course no hash ### Path Settings These options set the paths of various directories and files used by InvokeAI. Any user-defined paths should be absolute paths. ### Multi-GPU Generation On a machine with more than one GPU, InvokeAI can run several generation sessions at the same time — one per GPU — instead of processing the queue one job at a time. This is controlled by the `generation_devices` setting: ```yaml generation_devices: auto # default value ``` | Value | Behavior | |----------------------|-------------------------------------------------------------------------| | `auto` | Use every available CUDA GPU, running one generation session per GPU concurrently. This is the default. | | `[cuda:0,cuda:1]` | Use the specific devices listed, one session per device. Useful for reserving a GPU for other work. | | `[cuda:0]` | Use a single specific device. Generation runs serially, as it did before multi-GPU support. | ### Text Encoder Offload to Idle GPUs When more than one GPU is configured for generation but not all of them are busy, InvokeAI can run a session’s text/prompt encoder on a currently-idle GPU instead of the GPU running its denoise pipeline. This avoids evicting the denoise model from VRAM just to make room for the encoder, and lets the cached encoder be reused across generations — making repeated generations noticeably smoother. This is controlled by the `offload_text_encoders_to_idle_gpus` setting: ```yaml offload_text_encoders_to_idle_gpus: true # default value ``` ### Image Subfolder Strategy By default, generated images are stored in a single flat directory under `outputs/images/`. The `image_subfolder_strategy` setting lets you organize newly-created images into subfolders automatically. You can edit this setting in `invokeai.yaml` or, as an admin user, in the Settings panel. ```yaml image_subfolder_strategy: flat # default value ``` Available strategies: | Strategy | Example Path | Description | |----------|----------------------------|---------------------------------------------------------| | `flat` | `outputs/images/abc123.png`| Store images directly in the images directory. | | `date` | `outputs/images/2026/03/17/abc123.png` | Organize images by creation date. | | `type` | `outputs/images/general/abc123.png`| Organize images by image category. | | `hash` | `outputs/images/ab/abc123.png`| Use the first two characters of the image UUID for filesystem performance with large collections.| Changing this setting only affects newly-created images. Existing images remain in their current locations unless you run [Image Storage Maintenance](/content/features/image-storage-maintenance/index.html). ### Logging Several different log handler destinations are available, and multiple destinations are supported by providing a list: ```yaml log_handlers: - console - syslog=localhost - file=/var/log/invokeai.log ``` ### Environment Variables All settings may be set via environment variables by prefixing `INVOKEAI_` to the variable name. For example, `INVOKEAI_HOST` would set the `host` setting. ### CLI Args A subset of settings may be specified using CLI args: - `--root`: specify the root directory - `--config`: override the default `invokeai.yaml` file location ### Low-VRAM Mode See the [Low-VRAM mode docs](/content/configuration/low-vram-mode/index.html) for details on enabling this feature. ### All Settings The full settings reference is below. Additional explanations for selected settings appear earlier on this page.