How to Load Models from the Local Filesystem Instead of the Hugging Face Hub in Transformers.js

To load models from the local filesystem instead of the Hugging Face Hub, set env.allowRemoteModels = false and configure env.localModelPath in src/env.js, or pass local_files_only: true to specific getModelFile calls.

The Hugging Face transformers.js library defaults to downloading models from the Hugging Face Hub, but the source code provides granular environment controls to force local filesystem loading. By manipulating the global env configuration or per-call options, you can run inference entirely offline using pre-downloaded ONNX weights or custom models stored locally.

Understanding the Model Loading Pipeline

The core logic that determines where model files are fetched resides in the loadResourceFile function within src/utils/hub.js (lines 41‑71). This function orchestrates the resolution of model paths, cache checks, and the actual file retrieval from either local storage or remote URLs.

According to the huggingface/transformers.js source code, the loader follows a priority-based decision tree: it first checks the cache, then attempts local filesystem resolution if enabled, and finally falls back to remote fetching only if permitted and local files are absent.

Environment Configuration Flags

Four primary configuration options in src/env.js and src/utils/hub.js control local loading behavior.

Global Remote Access Control

env.allowRemoteModels (defined in src/env.js lines 30‑33) acts as the master switch for network access. When set to false, the library blocks all attempts to download from remoteHost, effectively enabling offline-only mode equivalent to local_files_only=true.

Local Filesystem Permissions

env.allowLocalModels (defined in src/env.js lines 34‑36) enables the library to search for files on the local filesystem. Note that env.useFS must also be true for this to function. In browser environments, this defaults to false, while Node.js environments typically default to true.

Local Model Path Resolution

env.localModelPath (defined in src/env.js lines 40‑43) specifies the base directory prefixed to model IDs during local path resolution. When you reference a model like "bert-base-uncased", the loader constructs the full path by combining this base directory with the model ID and requested filename.

Per-Call Overrides

options.local_files_only (processed in hub.js lines 29‑34) allows you to enforce local-only loading for individual getModelFile or pipeline calls without modifying global state. This overrides the environment flags for that specific request.

The Loading Sequence

When loadResourceFile executes, it follows this exact sequence as implemented in src/utils/hub.js:

1. Build Resource Paths – The buildResourcePaths function (lines 24‑38) constructs the requestURL, localPath, and remoteURL based on the supplied path_or_repo_id and filename.

2. Cache Verification – The system checks for cached resources via checkCachedResource, but proceeds to file resolution if nothing is cached.

3. Local Filesystem Lookup – If env.allowLocalModels is enabled and the requestURL is not a valid URL, the code invokes getFile(localPath), which utilizes the FileSystem API when env.useFS is true (lines 72‑78). Failure here falls through to remote fetching.

4. Remote Fetch – When the local path is missing, env.allowRemoteModels is true, and the model ID is valid, the library fetches remoteURL using env.fetch (lines 94‑102). The response is cached and returned as a Uint8Array.

5. Return – If return_path is requested (Node.js only), the function returns the local file path string; otherwise, it returns the file buffer.

Implementation Examples

Disable All Remote Downloads Globally

Set env.allowRemoteModels to false to prevent any network requests across your entire application:

import { env } from '@huggingface/transformers';

// Disallow any remote fetches for the whole process
env.allowRemoteModels = false;

After this configuration, loadResourceFile will never invoke fetch. Any missing local file will trigger an error (or return null if fatal=false).

Configure a Custom Local Directory

Point the loader to a specific directory containing your pre-downloaded models:

import { env } from '@huggingface/transformers';

// Example: models are stored under "./my_models/"
env.localModelPath = `${process.cwd()}/my_models/`;

When env.allowLocalModels is true (default on Node.js), a model ID like "bert-base-uncased" resolves to ./my_models/bert-base-uncased/ plus the requested filename.

Load a Specific Model with Local-Only Enforcement

Use the local_files_only option to force local loading for a single call without global side effects:

import { getModelFile } from '@huggingface/transformers';

// Load the ONNX weights from a local folder, never contacting the hub
const buffer = await getModelFile(
  './my_models/bert-base-uncased',   // local directory (or absolute path)
  'model.onnx',
  true,                              // fatal – throw if not found
  { local_files_only: true }         // enforce local-only for this call
);

The local_files_only flag short-circuits the remote-fallback logic (see hub.js lines 85‑90).

Configure a Purely Local Environment

Combine multiple flags to create an offline-only configuration:

import { env } from '@huggingface/transformers';

// Turn off remote loading and ensure local discovery is enabled
env.allowRemoteModels = false;
env.allowLocalModels = true;        // usually true on Node, explicit here for clarity
env.localModelPath = '/opt/models/'; // absolute path on the server

// Now any pipeline that references a model id will resolve from /opt/models/

Combine Local Loading with Custom Caching

You can use a custom cache implementation while still loading from local files:

import { env, getModelFile } from '@huggingface/transformers';

// Provide a custom cache implementation (must expose `match` and `put`)
env.useCustomCache = true;
env.customCache = myCacheObject;

const tensor = await getModelFile(
  'my-local-model',
  'model.onnx',
  true,
  { cache_dir: '/tmp/my_cache' }   // optional per-call override
);

The custom cache is consulted after the local file lookup, allowing you to cache the buffer of a locally-found model for later reuse.

Summary

• Global control: Set env.allowRemoteModels = false in src/env.js to block all Hugging Face Hub downloads.
• Local path configuration: Use env.localModelPath to define the base directory for local model resolution.
• Granular control: Pass { local_files_only: true } to getModelFile or pipeline calls for per-request local enforcement.
• Node.js vs Browser: env.allowLocalModels defaults to true in Node.js but false in browsers; explicitly enable it when needed.
• Implementation: The logic resides in loadResourceFile (src/utils/hub.js lines 41‑71), which checks local files before attempting remote fetches.

Frequently Asked Questions

How do I completely disable internet access in Transformers.js?

Set env.allowRemoteModels = false in your application initialization. According to the source code in src/env.js (lines 30‑33), this flag prevents loadResourceFile from ever calling the remote host, ensuring all models load from your local filesystem or fail if not found.

Can I use both local and remote models in the same application?

Yes. Keep env.allowRemoteModels as true (default) and env.allowLocalModels as true. The loading sequence in src/utils/hub.js (lines 72‑102) checks local paths first, then falls back to remote URLs only if the local file is absent. Alternatively, use the local_files_only per-call option to force local loading for specific models while allowing others to download from the Hub.

What file structure does Transformers.js expect for local models?

The library constructs paths by joining env.localModelPath + model_id + filename. For example, with env.localModelPath set to ./my_models/ and a request for bert-base-uncased with file model.onnx, the system looks for ./my_models/bert-base-uncased/model.onnx. Ensure your local directory mirrors the Hugging Face Hub repository structure, or use absolute paths in your model IDs.

Does local model loading work in the browser?

Local filesystem loading requires env.useFS to be true and env.allowLocalModels to be true. However, browsers sandbox filesystem access, so this configuration primarily works in Node.js environments. For browser usage, you typically need to serve local model files via a local HTTP server and point env.remoteHost to that endpoint, or use the File System Access API with specific user permissions.

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