`config.json` or `configuration.json` in HF Transformers models

[anthony8lee]

I’ve been seeing config.json and configuration.json being referenced in the various documentation I’ve read. However, I have only been able to find config.json being referenced in HF Transformers’s source here.

Was the configuration file name changed at some point during the release cycle? If so, I can’t find a changelog mentioning this.
Should I expect config.json and configuration.json to be both acceptable?

[John6666]

The special configuration file name has always been config.json and hasn’t changed.

When placing it in the same folder as an optional configuration file, the filename can usually be anything.

---

Answer

Was the filename changed?

No.

Transformers has treated the canonical config filename for a model directory / Hub repo as config.json for years via the constant CONFIG_NAME = "config.json" (e.g., in Transformers v3.2.0 and v4.2.2). (Hugging Face)

Why do docs mention configuration.json?

Because from_pretrained(...) accepts either:

• a directory (expects config.json inside), or
• a path/URL to a JSON file (filename can be anything)

The docs use ./my_model_directory/configuration.json as an example of the “explicit JSON file path” case. (Hugging Face)

Are both acceptable?

It depends on what you pass to from_pretrained().

What the loader actually does

In the config-loading path, Transformers resolves the config like this:

• If input is a directory → os.path.join(dir, CONFIG_NAME) → .../config.json
• If input is a file path or URL → use it as-is (so configuration.json works)
• If input is a Hub model id → download filename=CONFIG_NAME → config.json (Hugging Face)

Practical rule

• Directory / Hub repo: must contain config.json (the convention most tools rely on). (Hugging Face)
• Explicit JSON file path: any filename works (including configuration.json, my_configuration.json, etc.). (Hugging Face)

---

Quick examples

from transformers import AutoConfig

# Directory load -> expects ./my_model_dir/config.json
cfg = AutoConfig.from_pretrained("./my_model_dir")

# File load -> any filename works
cfg = AutoConfig.from_pretrained("./my_model_dir/configuration.json")
cfg = AutoConfig.from_pretrained("./my_model_dir/my_configuration.json")

The “directory must contain config.json” expectation is also reflected in the error messaging when it can’t find the file. (Hugging Face)

---

Recommendation (what to implement / expect)

• If you’re publishing a model folder or Hub repo: ship config.json.
• If you’re writing tooling and want to be permissive: you can accept configuration.json only when it’s explicitly provided as a file, or implement a fallback when config.json is missing—but that fallback is non-standard and may break other tooling that assumes config.json. (Hugging Face)

[anthony8lee]

Ahhh, I see and that makes sense now! Thank you for such detailed explanation.