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

> Learn how to load models locally in Transformers.js. Disable remote access and specify local model paths for faster, offline inference.

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

---

**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`](https://github.com/huggingface/transformers.js/blob/main/src/env.js), or pass `local_files_only: true` to specific `getModelFile` calls.**

The Hugging Face [`transformers.js`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/src/env.js) and [`src/utils/hub.js`](https://github.com/huggingface/transformers.js/blob/main/src/utils/hub.js) control local loading behavior.

### Global Remote Access Control

**`env.allowRemoteModels`** (defined in [`src/env.js`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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`](https://github.com/huggingface/transformers.js/blob/main/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:

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

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

```javascript
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`](https://github.com/huggingface/transformers.js/blob/main/hub.js) lines 85‑90).

### Configure a Purely Local Environment

Combine multiple flags to create an offline-only configuration:

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

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