Python Joblib Save Load Sklearn Models

When you train a scikit-learn model, you usually need to persist it for later inference or retraining. The standard tool for this is joblib, which is included as a dependency of scikit-learn. The pattern for python joblib save load sklearn models is straightforward: use joblib.dump to write the model to disk and joblib.load to read it back. This article covers the exact syntax, the parameters that matter, and the practical considerations that affect production use.

Why joblib for scikit-learn Models

Scikit-learn models often contain large NumPy arrays, such as the coefficients of a linear model or the tree structures of a random forest. Python's built-in pickle can serialize these objects, but joblib is optimized for arrays. It uses a more efficient binary format and can handle memory mapping, which is useful when a model is too large to fit into RAM.

Joblib also preserves the Python object graph correctly, including references to custom classes and functions, as long as those classes are importable at load time. For most scikit-learn estimators, joblib is the recommended serialization method.

Saving a Model with joblib.dump

The joblib.dump function writes an object to a file. Its basic usage is:

import joblib
from sklearn.ensemble import RandomForestClassifier

model = RandomForestClassifier(n_estimators=100)
# Assume model.fit(X_train, y_train) has been called

joblib.dump(model, 'model.joblib')

The first argument is the object to save, and the second is the file path. The file extension is arbitrary, but .joblib is conventional. You can also pass a file-like object, such as a BytesIO stream, if you need to keep the data in memory.

joblib.dump returns the list of file names it wrote. In most cases you can ignore this return value.

Loading a Model with joblib.load

Loading is symmetric:

import joblib

model = joblib.load('model.joblib')

The load function reads the object from disk and returns it. The object is reconstructed with the same class and state it had when saved. You can then call predict or transform on it directly.

predictions = model.predict(X_new)

Make sure the Python environment where you load the model has the same version of scikit-learn (or at least a compatible one) and any custom classes the model depends on.

Compression and File Size

Models can be large, especially ensemble methods with many trees. joblib.dump accepts a compress parameter that reduces the file size at the cost of slower save and load times.

joblib.dump(model, 'model_compressed.joblib', compress=3)

The value can be an integer from 0 to 9, where 0 disables compression and higher values give better compression at the cost of speed. You can also pass a tuple like ('zlib', 3) to choose a specific compression method. The default is 0 (no compression).

Compression is useful when you need to store models on disk or transfer them over a network. However, for frequently loaded models, the extra decompression time may not be worth it. Test with your actual model to find a balance.

Handling Versions and Compatibility

Serialized models are tied to the exact class definitions and the version of scikit-learn that created them. Loading a model with a different scikit-learn version can fail or, worse, produce silently incorrect results.

Joblib itself is relatively stable, but the underlying estimator classes may change between scikit-learn releases. When you upgrade scikit-learn, retrain and re-save your models rather than relying on old files. If you must load an old model, verify its predictions against a known baseline.

Similarly, if your model uses custom transformers or estimators defined in your own code, those classes must be importable in the loading environment. The load function will raise an ImportError if the class cannot be found.

Common Pitfalls and Errors

One frequent mistake is saving the model after fitting but before the training data is fully processed, or saving a model that references a large dataset unnecessarily. For example, some scikit-learn estimators store the training data in attributes like estimators_ or support_vectors_. This can bloat the file size. Consider whether you need those attributes for inference.

Another issue is using a file path with a relative directory that does not exist. joblib.dump will raise a FileNotFoundError if the parent directory is missing. Always create the directory first.

When loading, a common error is a missing module. If you see ModuleNotFoundError: No module named 'my_custom_transformer', it means the class is not importable in the current environment. Ensure your custom code is on sys.path or installed as a package.

Performance and Memory Considerations

For very large models, joblib supports memory mapping via the mmap_mode parameter in load. This allows you to load a model without copying all its arrays into RAM, which is useful when multiple processes share the same model file.

model = joblib.load('large_model.joblib', mmap_mode='r')

The 'r' mode opens the file read-only and maps it into memory. This reduces load time and memory usage, but you must not modify the model in place. If you need to retrain, load with mmap_mode=None (the default) to get a writable copy.

Memory mapping works best on local filesystems. Network filesystems may not support it reliably.

When to Use joblib vs pickle

Python's pickle can serialize any object, but joblib is specifically optimized for large NumPy arrays and is the recommended choice for scikit-learn models. Use pickle only if you have a special reason, such as needing to integrate with a system that already uses pickle and cannot add joblib as a dependency.

Joblib also offers compression and memory mapping out of the box, which are not available in the standard pickle module without extra code. For production deployments, joblib is the safer and more efficient option.

If you are saving multiple related objects, such as a model and its preprocessing pipeline, you can save them as a tuple or a dictionary in a single joblib file. This keeps the serialization atomic and simplifies versioning.

pipeline = {'scaler': scaler, 'model': model}
joblib.dump(pipeline, 'full_pipeline.joblib')

Loading returns the same dictionary, so you can access both components. This pattern is common in real projects and avoids managing multiple files.