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

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 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, 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:

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:

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, lines 41-51) accepts identical options:

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 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

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

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.
• 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 treats any valid Git reference identically, so commit hashes from PR branches work the same as tagged releases:

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

Does using different revisions duplicate cached files?

Yes, intentionally. The cache key logic in 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 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.

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