How to Configure extra_model_paths.yaml to Share Models Between ComfyUI Installations

ComfyUI uses extra_model_paths.yaml to register additional filesystem locations with the central folder_paths registry, allowing multiple installations to share a single model repository without duplicating files.

ComfyUI supports external model path configurations that extend the default folder structure, enabling users to share models across multiple installations or organize assets on external drives. By configuring extra_model_paths.yaml according to the Comfy-Org/ComfyUI source code specifications, you can map logical folder names like checkpoints and loras to any absolute or relative filesystem location, and the system will treat them as native folders.

How the Extra Model Paths System Works

According to the ComfyUI source code, the configuration system relies on two core components: utils/extra_config.py handles YAML parsing and path resolution, while folder_paths.py maintains the central registry. When load_extra_path_config() processes your YAML file, it expands environment variables and relative paths (including ~ for home directories), then registers each location via add_model_folder_path().

The UI and all downstream APIs query folder_paths.get_folder_paths() to locate assets. This means externally configured directories function identically to built-in folders, ensuring that whether models reside in the default models/checkpoints/ directory or a shared network drive, ComfyUI treats them as first-class citizens.

Creating Your extra_model_paths.yaml File

The YAML structure uses top-level section names to group related paths, with standard folder names such as checkpoints, loras, vae, and custom_nodes as keys.

Basic Configuration Syntax

A minimal configuration maps a folder type directly to a filesystem path:

shared_models:
  checkpoints: /mnt/nas/stable-diffusion/checkpoints
  loras: /mnt/nas/stable-diffusion/loras

Each key under the section represents a model type recognized by ComfyUI's folder registry in folder_paths.py.

Using base_path for Cleaner Configurations

To avoid repeating long path prefixes, define a base_path key that the loader automatically prepends to relative entries:

nas_storage:
  base_path: /mnt/shared/comfyui_models
  checkpoints: checkpoints
  loras: loras
  vae: vae

The loader in utils/extra_config.py resolves base_path first, then joins it with each relative subfolder before calling the registration functions.

Prioritizing Shared Locations with is_default

Add is_default: true to any section to insert those paths at the front of the search order:

primary_storage:
  base_path: ~/models/shared
  is_default: true
  checkpoints: checkpoints

As implemented in folder_paths.py, the add_model_folder_path() method checks this flag to determine whether to prepend or append the path to the internal list, affecting the order shown in the UI file browser.

Loading the Configuration into ComfyUI

ComfyUI discovers extra_model_paths.yaml through two mechanisms defined in main.py and comfy/cli_args.py.

Automatic Loading from the Installation Directory

If you place a file named exactly extra_model_paths.yaml in the same directory as main.py, ComfyUI automatically loads it during startup (lines 82-88 in main.py). This requires no command-line arguments:

python main.py

Specifying Custom Locations via CLI

For multiple configurations or files stored elsewhere, use the --extra-model-paths-config flag defined in comfy/cli_args.py:

python main.py --extra-model-paths-config /path/to/shared_models.yaml

You can pass this flag multiple times to load several configuration files simultaneously.

Complete Configuration Examples

Sharing Models Across Multiple Installations

This configuration points to a centralized NAS storage while keeping local models as fallback:

# extra_model_paths.yaml

shared_nas:
  base_path: /mnt/nas/ai_models
  is_default: true
  checkpoints: checkpoints
  loras: loras
  controlnet: controlnet
  
local_fallback:
  checkpoints: ./models/checkpoints

Cross-Platform Path Expansion

The loader supports environment variables and home directory expansion, verified in tests-unit/utils/extra_config_test.py:

windows_shared:
  base_path: "%APPDATA%/ComfyUI/shared_models"
  checkpoints: checkpoints
  
linux_home:
  base_path: ~/ai-models/shared
  loras: loras

Programmatic Loading

For custom scripts or extensions, import the utility directly from the source:

from utils import extra_config

extra_config.load_extra_path_config("/absolute/path/to/config.yaml")

# Paths are now available via folder_paths.get_folder_paths("checkpoints")

Summary

• Configuration file: Create extra_model_paths.yaml using standard folder names like checkpoints and loras as keys mapped to filesystem locations.
• Path resolution: The utils/extra_config.py loader expands ~, environment variables, and relative paths automatically before registration.
• Loading methods: Place the file next to main.py for auto-discovery, or use --extra-model-paths-config for explicit control over file locations.
• Search priority: Set is_default: true to prioritize shared folders over local installation directories.
• System integration: Registered paths function identically to default folders because all ComfyUI components query the centralized folder_paths registry via get_folder_paths().

Frequently Asked Questions

What is the exact filename required for automatic loading?

The file must be named exactly extra_model_paths.yaml and placed in the root directory containing main.py. As shown in main.py lines 82-88, ComfyUI checks for this specific filename during startup before processing command-line arguments. Any other name requires explicit loading via the --extra-model-paths-config flag.

Can I use environment variables in the path definitions?

Yes. According to tests-unit/utils/extra_config_test.py, the loader correctly expands system environment variables such as %APPDATA% on Windows and $HOME or ~ on Unix systems when resolving paths in your YAML configuration.

How do I ensure shared models appear before local ones in the file browser?

Set is_default: true within your YAML section. This flag triggers folder_paths.add_model_folder_path() to insert those paths at the beginning of the internal list rather than appending them, making shared content appear first in the UI and API responses.

Does this configuration method work for custom_nodes and other non-model folders?

Yes. While commonly used for checkpoints and loras, the system supports any folder type registered in folder_paths.py, including custom_nodes, vae, clip, and controlnet. Simply use the appropriate logical folder name as the key in your YAML file, and the registry will handle it accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}