Organizing Model Files in Subfolders within Hugging Face Repositories: The Complete Transformers.js Guide

Transformers.js can load ONNX models from any subfolder within a Hugging Face repository by specifying the subfolder option in AutoModel.from_pretrained(), defaulting to 'onnx' when omitted.

Transformers.js enables seamless browser-based inference by fetching model artifacts directly from the Hugging Face Hub. When working with complex repositories that contain multiple model variants or organized directory structures, understanding how to reference files inside subdirectories is essential for maintaining clean asset management and avoiding naming conflicts.

How Subfolder Resolution Works in Transformers.js

The library implements subfolder awareness through a coordinated pipeline spanning three core utility modules. When you invoke from_pretrained(), the subfolder parameter propagates through the entire download and caching chain, ensuring all artifacts—including weight files, configuration JSON, and external data chunks—resolve correctly.

The PretrainedModelOptions Interface

In src/utils/hub.js (lines 38-46), the PretrainedModelOptions type definition declares the subfolder field with a default string value of 'onnx'. This configuration object is passed through every subsequent loader function, ensuring consistent path resolution across the codebase.

Internal Path Construction with buildResourcePaths

The buildResourcePaths function in src/utils/hub.js (lines 24-48) serves as the central path builder. It accepts the repository identifier, filename, and options object, then constructs both the remote Hugging Face Hub URL and the local cache path by prefixing the requested filename with options.subfolder.

File Enumeration in get_model_files

Located in src/utils/model_registry/get_model_files.js (lines 36-38), this utility generates the complete list of files required for model initialization. It automatically prepends the configured subfolder to every artifact name, including the core ONNX file, generation configuration, and external data shards.

Default Behavior and the 'onnx' Convention

By default, Transformers.js assumes model artifacts reside in an onnx/ directory at the repository root. This convention aligns with standard Hugging Face Hub practices for ONNX model storage. If your repository follows this structure, no additional configuration is required, and the loader resolves paths like https://huggingface.co/<repo>/resolve/main/onnx/model.onnx automatically.

Practical Code Examples

Loading from the Default onnx Folder

When your model follows the standard repository structure, simply call from_pretrained() with the repository identifier:

import { AutoModel } from '@xenova/transformers';

// Resolves to onnx/model.onnx and associated config files
const model = await AutoModel.from_pretrained('onnx-community/granite-4.0-350m-ONNX-web');

Specifying a Custom Subfolder

For repositories storing artifacts in non-standard directories like custom/ or weights/:

import { AutoModel } from '@xenova/transformers';

// Targets the custom/ directory containing model.onnx
const model = await AutoModel.from_pretrained(
  'my-org/my-model',
  { subfolder: 'custom' }
);

Internally, buildResourcePaths generates the remote URL https://huggingface.co/my-org/my-model/resolve/main/custom/model.onnx and caches the file under <cache_dir>/my-org/my-model/custom/model.onnx.

Handling Custom Model File Names

When the ONNX file uses a non-standard name within a subfolder, combine the subfolder and model_file_name options:

import { AutoModel } from '@xenova/transformers';

const model = await AutoModel.from_pretrained(
  'my-org/multi-model-repo',
  {
    subfolder: 'encoders',           // Directory path
    model_file_name: 'my_encoder'    // Resolves to encoders/my_encoder.onnx
  }
);

The get_model_files utility (lines 24-30) uses model_file_name to construct the final path while maintaining the subfolder prefix.

Loading External Data Chunks from Subfolders

For large models using the external data format (use_external_data_format: true), the loader automatically resolves chunk files like model.onnx_data0 from the same subfolder:

import { AutoModel } from '@xenova/transformers';

// Resolves large/model.onnx and large/model.onnx_data0
const model = await AutoModel.from_pretrained(
  'big-model-repo',
  { subfolder: 'large' }
);

Internally, resolveExternalDataFormat in src/utils/model-loader.js determines the number of chunks needed, and getExternalDataChunkNames yields filenames that are then prefixed with the subfolder path by getCoreModelFile and getModelDataFiles (lines 44-48).

Key Implementation Files

File	Purpose
src/utils/hub.js	Defines PretrainedModelOptions.subfolder and implements buildResourcePaths for URL and cache path generation.
src/utils/model_registry/get_model_files.js	Enumerates all downloadable artifacts, consistently prepending the configured subfolder to each filename.
src/utils/model-loader.js	Contains getCoreModelFile and getModelDataFiles for resolving full paths, including external data chunks.
src/transformers.js	Public API entry point (AutoModel.from_pretrained) that forwards the subfolder option to internal loaders.

Summary

• Default location: Transformers.js searches for models in the onnx/ subfolder unless the subfolder option overrides this.
• Path resolution: The subfolder parameter propagates through buildResourcePaths, get_model_files, and getCoreModelFile to construct correct remote URLs and local cache keys.
• External data support: Weight shards (e.g., model.onnx_data0) are automatically resolved within the same subfolder when using external data formats.
• Repository organization: Multiple model variants can coexist in a single repository using distinct subfolders, accessed via the subfolder option in from_pretrained().

Frequently Asked Questions

What is the default subfolder for models in Transformers.js?

The default subfolder is 'onnx', as explicitly defined in src/utils/hub.js (lines 38-46). If you omit the subfolder option when calling from_pretrained(), the loader automatically searches for all model files inside an onnx/ directory at the repository root.

Can I use nested subfolders (subfolders within subfolders)?

Yes. You can specify nested directory structures using standard path notation such as subfolder: 'path/to/model'. The buildResourcePaths function treats the subfolder string as a literal path prefix, constructing URLs like https://huggingface.co/<repo>/resolve/main/path/to/model/model.onnx.

How does the subfolder parameter affect caching?

The subfolder name becomes part of the cache key generation. In buildResourcePaths (lines 24-48), the local filesystem path includes the subfolder directory structure, ensuring that models from different subfolders within the same repository are cached separately without file collisions.

Does the subfolder option work with all model types?

Yes. The subfolder option is universal across all AutoModel classes (e.g., AutoModelForSequenceClassification, AutoModelForCausalLM) and pipelines in Transformers.js. Whether loading encoder-only, decoder-only, or encoder-decoder architectures, the subfolder resolution logic in get_model_files and model-loader.js applies consistently to all model artifacts.

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