Clarify build_sam2 config_file contract and support external config dirs

[omry]

build_sam2() currently accepts an argument named config_file and passes it directly to Hydra as config_name:

sam2/sam2/build_sam.py

Lines 69 to 92 in 2b90b9f

	def build_sam2(
	config_file,
	ckpt_path=None,
	device="cuda",
	mode="eval",
	hydra_overrides_extra=[],
	apply_postprocessing=True,
	**kwargs,
	):
	if apply_postprocessing:
	hydra_overrides_extra = hydra_overrides_extra.copy()
	hydra_overrides_extra += [
	# dynamically fall back to multi-mask if the single mask is not stable
	"++model.sam_mask_decoder_extra_args.dynamic_multimask_via_stability=true",
	"++model.sam_mask_decoder_extra_args.dynamic_multimask_stability_delta=0.05",
	"++model.sam_mask_decoder_extra_args.dynamic_multimask_stability_thresh=0.98",
	]
	# Read config and init model
	cfg = compose(config_name=config_file, overrides=hydra_overrides_extra)
	OmegaConf.resolve(cfg)
	model = instantiate(cfg.model, _recursive_=True)

cfg = compose(config_name=config_file, overrides=hydra_overrides_extra)

SAM2 initializes Hydra with the sam2 config module:

https://github.com/facebookresearch/sam2/blob/2b90b9f5ceec907a1c18123530e92e794ad901a4/sam2/__init__.py

initialize_config_module("sam2", version_base="1.2")

That means config_file is not a generic filesystem path. It is a Hydra config name/path resolved inside Hydra's initialized config search path, for example:

"configs/sam2.1/sam2.1_hiera_l.yaml"

This has confused users who pass absolute filesystem paths like:

"/kaggle/working/models/sam2.1_hiera_l.yaml"

Related reports:

• Loading models on Cloud services not working when using build_sam2 but works on Windows I am giving accurate paths #544
• [Bug] Hydra can't find local config file, requires an extra slash be prepended to the local path hydra#3033
• [Bug] Potential Error in get_config_path() For Absolute Paths hydra#3045

From Hydra's perspective, this is expected: compose(config_name=...) resolves a config name from the configured search path. It does not mean "load this arbitrary file path."

I think SAM2 should clarify this contract and, if external config files are supported, expose that explicitly. A clean API could accept an additional optional config directory/search path argument, then initialize or extend Hydra's config search path appropriately. Users would pass something like:

build_sam2(
    config_file="sam2.1_hiera_l.yaml",
    config_dir="/kaggle/working/models",
    ckpt_path=...,
)

or similar.

The important point is that config_file should remain a config name resolved inside the search path, while config_dir or an equivalent argument tells SAM2 where external configs live.

This avoids relying on the current double-slash workaround and gives users a clearer mental model:

• config_dir: where to search
• config_file / config_name: what config to compose from that search path

Can you clarify the intended contract for build_sam2(config_file=...) and consider adding an explicit external config directory option if loading user-provided config files is supported?

[omry]

Here is a user-side workaround that preserves Hydra's config model:

• config_dir is a directory added to Hydra's config search path.
• config_name is the Hydra config name resolved inside that directory.
• The helper registers a temporary primary config, then removes it after build_sam2() returns or raises.

This means the user config can also include additional subconfigs under config_dir via its own defaults list.

from pathlib import Path
from uuid import uuid4

from hydra.core.config_store import ConfigStore
from sam2.build_sam import build_sam2


def build_sam2_config_dir(config_dir, config_name, **kwargs):
    """Build SAM2 from a user config directory.

    config_dir is the directory added to Hydra's config search path.
    config_name is the Hydra config name resolved inside that directory, for
    example config_dir="/models/sam2" and config_name="sam2.1_hiera_l.yaml".
    See: https://hydra.cc/docs/advanced/search_path/
    """
    # Workaround for facebookresearch/sam2#758, tested with SAM2 commit
    # 2b90b9f5ceec907a1c18123530e92e794ad901a4. SAM2's build_sam2() expects a
    # Hydra config name, not an absolute file path. Keep config_dir and
    # config_name separate to match Hydra's config search path model.
    config_dir = Path(config_dir).resolve()
    wrapper_name = f"_sam2_external_config_{uuid4().hex}"

    try:
        # Register an alternative primary config. The user's config is then a
        # non-primary config resolved via hydra.searchpath.
        ConfigStore.instance().store(
            name=wrapper_name,
            node={
                "defaults": [
                    config_name[:-5] if config_name.endswith(".yaml") else config_name,
                    "_self_",
                ],
                "hydra": {"searchpath": [f"file://{config_dir}"]},
            },
        )
        return build_sam2(wrapper_name, **kwargs)
    finally:
        ConfigStore.instance().repo.pop(f"{wrapper_name}.yaml", None)

Example:

model = build_sam2_config_dir(
    config_dir="/path/to/my/sam2/configs",
    config_name="sam2.1_hiera_l.yaml",
    ckpt_path=checkpoint,
    device="cuda",
)

This was smoke-tested against SAM2 commit 2b90b9f5ceec907a1c18123530e92e794ad901a4 with a minimal SAM2-style config. The test covered the Hydra/SAM2 config-resolution behavior and verified that the temporary ConfigStore entry is cleaned up.