# How to Load Specific Model Revisions or Commits from Hugging Face Hub with transformers.js

> Easily load specific model revisions or commits from Hugging Face Hub using transformers.js. Control versions precisely and manage isolated caches with the revision option.

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

---

**[`transformers.js`](https://github.com/huggingface/transformers.js/blob/main/transformers.js) allows you to specify any Git-style revision (branch, tag, or commit SHA) via the `revision` option when loading models or tokenizers, ensuring precise version control and isolated caching.**

Loading specific model versions is essential for reproducible machine learning workflows. The [`huggingface/transformers.js`](https://github.com/huggingface/transformers.js/blob/main/huggingface/transformers.js) library provides native support for targeting exact revisions directly from the Hugging Face Hub, preventing version drift and enabling side-by-side comparisons of model checkpoints.

## Core Revision Handling in hub.js

The revision functionality is centralized in the core utilities, ensuring consistent behavior across all loading APIs.

### PretrainedOptions Type Definition

In [`packages/transformers/src/utils/hub.js`](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/utils/hub.js), the `PretrainedOptions` type explicitly declares the `revision` field with a default value of `'main'` (lines 33-35). This type serves as the foundation for all model and tokenizer loading functions, establishing the contract that every loading operation accepts a revision identifier.

### URL Construction and Resource Paths

The `buildResourcePaths` function (lines 24-46 in the same file) implements the actual revision resolution logic. It reads `options.revision` (falling back to `'main'`) and constructs the remote URL pointing to `huggingface.co` while simultaneously generating a unique cache key. When you request a non-default revision, the system incorporates that identifier into both the network request and the local storage path.

### Cache Isolation Logic

To prevent collisions between different versions of the same model, the cache key strategy adapts based on the revision parameter. According to the source code (lines 41-46), if you use the default `'main'` branch, the request URL itself serves as the cache key. However, when specifying a custom revision, the key becomes `<repo>/<revision>/<filename>`. This guarantees that `v1.0.0` and `v2.0.0` of the same repository occupy separate cache entries, allowing multiple versions to coexist locally without interference.

## Loading Models with Specific Revisions

All high-level model loading APIs forward the `revision` option through to the underlying hub utilities.

### Pipeline API

The `pipeline` function accepts a `revision` field in its options object and passes it directly to the model loader:

```javascript
import { pipeline } from '@huggingface/transformers';

const generator = await pipeline(
  'text-generation',
  'Xenova/gpt2',
  { revision: 'v1.2.0' }  // Branch name, tag, or full commit SHA
);
const result = await generator('The future of AI is');
console.log(result);

```

### AutoModel API

Similarly, `AutoModel.from_pretrained` propagates the revision parameter as implemented in [`packages/transformers/src/models/auto/modeling_auto.js`](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/models/auto/modeling_auto.js):

```javascript
import { AutoModel } from '@huggingface/transformers';

const model = await AutoModel.from_pretrained(
  'Xenova/distilbert-base-uncased',
  { revision: 'a1b2c3d' }  // Short commit hash works
);

```

## Loading Tokenizers from Specific Commits

Tokenizer loading follows the same revision resolution pattern. The `AutoTokenizer.from_pretrained` method (defined in [`packages/transformers/src/models/auto/tokenization_auto.js`](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/models/auto/tokenization_auto.js), lines 41-51) accepts identical options:

```javascript
import { AutoTokenizer } from '@huggingface/transformers';

const tokenizer = await AutoTokenizer.from_pretrained(
  'Xenova/bert-base-uncased',
  { revision: '4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v' }  // Full commit SHA
);

const encoded = await tokenizer('Transformers are great!');
console.log(encoded.input_ids);

```

## Managing Cached Revisions with ModelRegistry

The `ModelRegistry` class in [`packages/transformers/src/utils/model_registry/ModelRegistry.js`](https://github.com/huggingface/transformers.js/blob/main/packages/transformers/src/utils/model_registry/ModelRegistry.js) exposes revision-aware cache management utilities (lines 24-28). These methods allow you to inspect and purge specific versions without affecting other cached models.

### Checking Cache Status for a Revision

```javascript
import { ModelRegistry } from '@huggingface/transformers';

const status = await ModelRegistry.is_cached(
  'Xenova/gpt2',
  { revision: 'dev' }
);
console.log(status.allCached);  // true only if 'dev' revision files exist locally

```

### Clearing Specific Revision Cache

```javascript
await ModelRegistry.clear_cache('Xenova/gpt2', { revision: 'old-tag' });
console.log('Removed cached files for revision "old-tag"');

```

## Summary

- **`revision` option**: Accepts branch names, tags, or commit SHAs; defaults to `'main'` as defined in [`hub.js`](https://github.com/huggingface/transformers.js/blob/main/hub.js).
- **Cache isolation**: Non-default revisions use the key pattern `<repo>/<revision>/<filename>` to prevent version collisions.
- **Universal propagation**: All loading APIs (`pipeline`, `AutoModel`, `AutoTokenizer`) pass the revision parameter through to the underlying hub utilities.
- **Registry management**: `ModelRegistry` methods respect revision parameters for targeted cache inspection and cleanup.

## Frequently Asked Questions

### How do I load a model from a specific pull request commit?

Specify the full commit SHA in the `revision` field. The `buildResourcePaths` function in [`hub.js`](https://github.com/huggingface/transformers.js/blob/main/hub.js) treats any valid Git reference identically, so commit hashes from PR branches work the same as tagged releases:

```javascript
{ revision: 'abc123def456' }  // 40-character or abbreviated SHA

```

### Does using different revisions duplicate cached files?

Yes, intentionally. The cache key logic in [`hub.js`](https://github.com/huggingface/transformers.js/blob/main/hub.js) (lines 41-46) appends the revision to the storage path for non-default versions. This ensures complete isolation between versions, preventing one revision from overwriting another's weights.

### Can I use short commit hashes like in Git CLI?

While the system accepts abbreviated SHAs, the Hugging Face Hub API typically resolves them to full hashes internally. For maximum compatibility and clarity in production code, use the full 40-character SHA or named tags/branches rather than short hashes.

### What happens if the revision does not exist?

The request will fail during the remote resource fetch phase. Because [`transformers.js`](https://github.com/huggingface/transformers.js/blob/main/transformers.js) constructs the URL with your specified revision before checking the local cache, the Hugging Face Hub will return a 404 error for non-existent branches, tags, or commits, which propagates back through the loading promise as a rejection.