Introduction

A joblib.load error mentioning __main__ usually means the serialized object refers to a class or function that existed in the __main__ module when it was saved, but that same symbol is not available in __main__ when you load it.

This is not really a joblib-specific mystery. It is a serialization import-path problem. joblib relies on Python's pickle mechanics, and pickle needs to import the same class or function by module path when the object is reconstructed.

Why __main__ Causes Trouble

Suppose you train and save a model wrapper in a script where the class is defined directly in that script:

1import joblib
2
3class MyModel:
4    def __init__(self, value):
5        self.value = value
6
7joblib.dump(MyModel(10), "model.joblib")

When that script runs, the class lives under __main__.MyModel. If you later load the file from a different entry point, Python may not have MyModel in __main__ anymore, so loading fails with an AttributeError.

Move The Class Into An Importable Module

The durable fix is to define the class or helper function in a normal module, not in the top-level training script.

mymodel.py:

class MyModel:
    def __init__(self, value):
        self.value = value

Saving:

1import joblib
2from mymodel import MyModel
3
4joblib.dump(MyModel(10), "model.joblib")

Loading:

1import joblib
2from mymodel import MyModel
3
4obj = joblib.load("model.joblib")
5print(obj.value)

Now the object can be reconstructed by importing mymodel.MyModel, which is stable across scripts.

Import Before Loading

Sometimes the class is already in a module, but the loading script never imports it. In that case, importing the module before joblib.load can be enough. The larger principle is that the deserializer must be able to resolve the original symbol path.

Best Practice For Models And Pipelines

This issue is common in notebooks and training scripts because people define helper classes inline. That works until the artifact is loaded in a different process, deployment service, or notebook kernel.

The safer pattern is:

• define custom transformers and wrappers in importable modules
• version the code together with the serialized artifact
• load in an environment where those modules are installed and importable

That makes model artifacts much less fragile.

Notebooks Make This Worse

Jupyter notebooks are a common source of this error because training may happen in one notebook session where the class lives in __main__, while loading happens in a different kernel or deployment process. The object file looks fine, but the symbol path has changed underneath it.

Artifacts Depend On Code Version Too

This is also a reminder that serialized Python objects depend on the code that created them. Loading an artifact successfully often requires not just the same module path, but a compatible implementation of the class itself. Treat model files and the code defining custom objects as one deployment unit.

Common Pitfalls

• Defining custom classes only inside a training script or notebook cell.
• Saving objects whose classes live under __main__ and expecting them to load everywhere.
• Forgetting to import the defining module before loading.
• Treating the error as corrupted data when it is really a missing symbol problem.
• Assuming joblib is independent from pickle's import-path rules.

Summary

• A joblib.load __main__ AttributeError usually means pickle cannot find the original class or function path.
• Objects saved from a top-level script often get recorded under __main__.
• Move custom classes and functions into real importable modules.
• Import the defining module before loading the artifact.
• Treat serialized Python objects as code-dependent artifacts, not as self-contained universal files.