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

> Learn to organize model files in subfolders within Hugging Face repositories using Transformers.js. Load ONNX models easily by specifying the subfolder option in AutoModel.from_pretrained.

- Repository: [Hugging Face/transformers.js](https://github.com/huggingface/transformers.js)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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:

```javascript
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/`:

```javascript
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:

```javascript
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:

```javascript
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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/src/utils/hub.js)** | Defines `PretrainedModelOptions.subfolder` and implements `buildResourcePaths` for URL and cache path generation. |
| **[`src/utils/model_registry/get_model_files.js`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/src/utils/model-loader.js)** | Contains `getCoreModelFile` and `getModelDataFiles` for resolving full paths, including external data chunks. |
| **[`src/transformers.js`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/model-loader.js) applies consistently to all model artifacts.