huggingface/transformers

Configuration files

Where configuration of various flavours lives in the repository.

Per-model `config.json`

Every checkpoint on the Hub stores its hyperparameters in config.json. The Python side is the PretrainedConfig subclass at src/transformers/models/<arch>/configuration_<arch>.py. The base class is src/transformers/configuration_utils.py. Round-trips:

cfg = AutoConfig.from_pretrained("Qwen/Qwen2.5-1.5B")
cfg.to_json_string()       # serialize
cfg.save_pretrained("./out")
cfg.push_to_hub("my-org/my-cfg")

`generation_config.json`

Decoding hyperparameters (sampling, beam search, temperature, etc.) live in a separate GenerationConfig (src/transformers/generation/configuration_utils.py, 102K LOC). The split keeps generation knobs out of the model config so users can ship multiple decoding strategies for the same model. model.generation_config is loaded automatically by from_pretrained.

Tokenizer config files

A tokenizer typically writes:

tokenizer_config.json — pad/eos/bos token ids, model max length, special tokens map, optionally the chat template.
tokenizer.json — fast-tokenizer state (when applicable).
vocab.json + merges.txt — slow-tokenizer state (when applicable).
special_tokens_map.json — the canonical special-tokens mapping.
chat_template.json — the chat template if it does not fit in tokenizer_config.json.

Preprocessor configs

File	Used by
`preprocessor_config.json`	Image / video / feature extractors
`processor_config.json`	Multimodal `Processor` classes

Quantization configs

quantization_config is stored as a sub-key in config.json and reified via AutoQuantizationConfig. The dataclasses (BitsAndBytesConfig, GPTQConfig, AWQConfig, Mxfp4Config, HqqConfig, QuantoConfig, TorchAoConfig, FbgemmFp8Config, FineGrainedFp8Config, VptqConfig, SinqConfig, SpqrConfig, HiggsConfig, BitNetConfig, QuarkConfig, FpQuantConfig, AqlmConfig, EetqConfig, AutoRoundConfig, CompressedTensorsConfig, FourOverSixConfig, MetalQuantizationConfig) all live in src/transformers/utils/quantization_config.py (89K LOC).

Repo-level configuration

File	Purpose
`setup.py`	Dependencies, version range, build commands
`pyproject.toml`	`ruff`, `ty`, `pytest` configuration; supported Python = 3.10–3.14
`Makefile`	Developer entry points
`conftest.py`	Pytest fixtures, hub-timeout env var (`HF_HUB_DOWNLOAD_TIMEOUT=60`)
`.circleci/config.yml`	CI for PRs (CPU + lint)
`.github/workflows/*.yml`	CI for self-hosted GPUs and nightlies
`.gitignore`, `.gitattributes`	Standard
`.git-blame-ignore-revs`	Ignored bulk-format commits in `git blame`

Environment variables

Set by users to influence behaviour:

| Variable | Effect | | ------------------------------------ | ---------------------------------------------------- | ---- | ------- | ----- | --------- | | HF_HOME | Hub cache root (default ~/.cache/huggingface) | | HF_HUB_OFFLINE=1 | Disallow network calls | | TRANSFORMERS_OFFLINE=1 | Same, library-scoped | | HF_HUB_DOWNLOAD_TIMEOUT | HTTP timeout (seconds) | | TRANSFORMERS_VERBOSITY | debug | info | warning | error | critical | | TRANSFORMERS_CACHE | Legacy alias for HF_HOME (deprecated) | | HF_TOKEN | Hub authentication token (read by huggingface_hub) | | RUN_SLOW=1 | Enable tests gated by @slow | | SAFE_TENSORS_FAST_GPU | Fast safetensors loader on GPU | | OMP_NUM_THREADS, MKL_NUM_THREADS | Threading hints |

The full list is enforced by src/transformers/utils/import_utils.py (114K LOC) and surfaced in transformers env.