Introduction

torch.hub.load can load from a local directory as well as from GitHub. To make that work, the directory must behave like a Torch Hub repository: it needs a hubconf.py file that exposes callable entry points.

The Minimum Local Repository Shape

A small local hub repository usually looks like this:

1my_model_repo/
2  hubconf.py
3  my_models.py
4  checkpoints/
5    tiny_net.pt

The important file is hubconf.py. That is where Torch Hub looks for the named functions you want to load.

Define an Entry Point in hubconf.py

A simple local entry point can construct the model and optionally load weights.

1# hubconf.py
2import torch
3from my_models import TinyNet
4
5
6def tiny_net(pretrained=False, checkpoint_path=None):
7    model = TinyNet()
8    if pretrained:
9        if checkpoint_path is None:
10            raise ValueError("checkpoint_path is required")
11        state = torch.load(checkpoint_path, map_location="cpu")
12        model.load_state_dict(state)
13    model.eval()
14    return model

Each public function defined there becomes a load target.

Load the Model From a Local Path

Use the local repository path and set source="local".

1import torch
2
3model = torch.hub.load(
4    "/path/to/my_model_repo",
5    "tiny_net",
6    source="local",
7    pretrained=True,
8    checkpoint_path="/path/to/my_model_repo/checkpoints/tiny_net.pt",
9)
10
11x = torch.randn(1, 3, 64, 64)
12with torch.no_grad():
13    y = model(x)
14print(y.shape)

That tells Torch Hub not to resolve a GitHub repo. It should treat the first argument as a local directory.

Use torch.hub.list to Check the Entry Points

If loading fails because the function name is wrong or not exported the way you expect, inspect the available hub entry points.

import torch

print(torch.hub.list("/path/to/my_model_repo", source="local"))

If your expected function is not listed, the problem is usually in hubconf.py, not in the checkpoint.

Know When torch.hub.load Is the Right Tool

Use Torch Hub when you want a stable constructor-style API for models. It is especially useful when several scripts or teams should load models through the same public entry points.

If you already control the codebase and only need to restore weights inside one project, plain torch.load plus normal model construction may be simpler.

Torch Hub is an interface layer, not just a serialization shortcut.

Keep Code and Weights Compatible

Most local-loading failures are compatibility problems:

• the checkpoint was saved from an older architecture version
• the repository path is wrong
• 'hubconf.py imports the wrong module names'
• the checkpoint expects GPU tensors but the current environment loads on CPU

That is why a small smoke test after loading is worth keeping near the model package.

Keep the Entry Point Small and Stable

A good hubconf.py entry point should stay thin. It should mostly construct the model, load weights if requested, and return a ready-to-use object. If you hide too much environment-specific logic inside the entry point, local hub loading becomes harder to reuse and harder to debug.

Treat the entry point as a public loading API for the repository, not as a place for training-time assumptions.

Smoke-Test the Loaded Model Immediately

After loading, run one tiny forward pass or at least inspect the model summary. This catches shape mismatches, missing keys, and bad checkpoint paths at load time instead of much later in an inference job.

Common Pitfalls

The biggest mistake is forgetting source="local", which makes Torch Hub assume a remote GitHub source.

Another issue is pointing at a directory without a valid hubconf.py file.

A third problem is loading weights into a model definition that has changed since the checkpoint was created.

Summary

• 'torch.hub.load supports local directories when source="local" is used.'
• The directory must contain a hubconf.py file with loadable entry points.
• Pass checkpoint paths explicitly when the entry point expects them.
• Use torch.hub.list(..., source="local") to inspect available local functions.
• Keep the repository code and checkpoint files aligned so loading stays reproducible.