Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 38 ยท Machine Learning Apps

Saving, Loading and Sharing Models

Persist scikit-learn models for Streamlit with joblib, load them once with cache_resource, version them, retrain on demand with a button and avoid unsafe pickles.

Training a model inside a web app is fine for a demo with 150 rows. For anything bigger, training takes seconds or minutes and must not happen when a visitor opens the page. The standard answer is to train offline, save the fitted model to a file, and have the app only load it. This lesson covers saving with joblib, loading once with st.cache_resource, keeping the model and the app in sync with versions, retraining from a button, and the security rules around pickled files.

Two scripts, one file between them

flowchart LR
    T["train.py<br/>(you run it)"] -->|writes| F["model.joblib<br/>+ metadata.json"]
    F -->|read once| A["app.py<br/>cache_resource"]
    A --> U["Users"]

Training and serving are different jobs, so keep them in different files.

train.py runs on your machine or a schedule, reads data, fits the model and writes it out. app.py only reads. Because the files are separate, a slow or failing training run never breaks the app, and you can test each part on its own.

Saving with joblib

joblib is the standard way to store scikit-learn estimators. It handles large NumPy arrays efficiently.

Python
# train.py
import json
import joblib
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

iris = load_iris(as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(
    iris.data, iris.target, test_size=0.25, random_state=0, stratify=iris.target)

model = make_pipeline(StandardScaler(), RandomForestClassifier(random_state=0))
model.fit(X_train, y_train)

joblib.dump(model, "model.joblib")
with open("metadata.json", "w") as f:
    json.dump({
        "features": list(iris.data.columns),
        "classes": list(iris.target_names),
        "test_accuracy": round(model.score(X_test, y_test), 4),
        "sklearn_version": __import__("sklearn").__version__,
    }, f, indent=2)

Notice the pipeline: the scaler and the classifier are saved together, so the app can never forget to apply the same preprocessing as in training. Saving only the classifier and re-creating the scaler in the app is a classic bug that gives plausible but wrong predictions.

The metadata file records the feature names, class names, a score and the library version. The app uses it to build inputs and to show users what they are looking at.

Loading once with cache_resource

Python
# app.py
import json
import joblib
import streamlit as st

@st.cache_resource
def load_model():
    model = joblib.load("model.joblib")
    with open("metadata.json") as f:
        meta = json.load(f)
    return model, meta

model, meta = load_model()
st.caption(f"Test accuracy: {meta['test_accuracy']:.1%}")

The file is read on the first visit after a server start, and after that every session shares the same object (see Caching). Calling load_model.clear() forces a reload, useful after you swap the file.

Try the cycle: save to memory, reload, predict

Pyodide in the browser has no real disk, but joblib works with in-memory buffers, so you can verify the round trip: a reloaded model must predict exactly like the original.

Python Round trip: dump and load with joblib

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The reloaded pipeline gives identical predictions, including the scaler's learned statistics.

Versions and compatibility

A pickled or joblib file is tied to the library versions that created it. Loading a model saved with scikit-learn 1.4 under 1.7 may warn or break. Protect yourself:

  • Pin versions in requirements.txt (scikit-learn==1.7.2) and train with the same ones.
  • Store the version in the metadata, and check it when loading:
Python
import sklearn
if meta["sklearn_version"] != sklearn.__version__:
    st.warning("The model was trained with a different scikit-learn version.")
  • Put a version or date in the file name (model-2026-11-01.joblib) and have the app read the latest. That way you can roll back by pointing to the previous file.
  • For a long-lived model, consider an interchange format such as ONNX, which does not depend on the Python class definitions.

Security: do not load untrusted pickles

joblib.load and pickle.load can execute arbitrary code from the file. Only load files that you or your pipeline created and that cannot be modified by users. In particular:

  • Never let users upload a model file and then joblib.load it. Upload data, not models.
  • Do not fetch a model from a URL you do not control without a checksum.
  • Protect the folder (or bucket) the model lives in with proper permissions.

A simple hardening step is to check a SHA-256 hash recorded at training time:

Python
import hashlib

def sha256_of(path):
    return hashlib.sha256(open(path, "rb").read()).hexdigest()

if sha256_of("model.joblib") != meta["sha256"]:
    st.error("Model file does not match its recorded hash.")
    st.stop()

This confirms the file is the one your training script wrote, which catches corruption and accidental swaps. You compute the hash in train.py and write it into metadata.json (the metadata file itself must also be trusted).

A retrain button

Sometimes users (or you) want to retrain from the app with new settings, for instance the number of trees. Treat this as an explicit, rare action, not something that runs on every rerun:

Python
n_trees = st.slider("Trees", 10, 300, 100, step=10)
if st.button("Retrain"):
    with st.spinner("Training..."):
        new_model = train_model(n_trees)              # your own function
        st.session_state.model = new_model             # this user's model only
    st.success("Done.")

model = st.session_state.get("model") or load_model()[0]

Storing the retrained model in st.session_state gives that user their own model, without changing what everyone else sees (see Session State). Replacing the shared cached model for all users would be a decision about your product, not about a slider, and it needs protection (a login, the metadata update, a lock so two retrains do not collide).

Long training runs do not belong in the request: Streamlit may time out proxies and the user cannot cancel. For anything beyond a few seconds run training as a background job and let the app load the finished file.

Here is a stand-in that shows the cache-plus-retrain logic with call counters, using a trivial "model" so it runs instantly.

Python Stand-in: shared cache and per-session retrain

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

User a gets a private retrained model; user b still shares the original, and the shared model was trained only once.

Where to keep large files

GitHub limits normal files to 100 MB, and big binaries make the repository heavy. For models above a few megabytes, store them in object storage (S3, Google Cloud Storage, Hugging Face Hub) and download once at startup into a cached function. Verify the hash after download, and keep the download credentials in st.secrets (APIs and Secrets). Git LFS is another option if your host supports it.

Common mistakes

  • Saving the classifier without its preprocessing pipeline.
  • Training and serving with different library versions.
  • Loading a model that users can influence (pickle code execution).
  • Retraining on every rerun or for every user visit.
  • Committing multi-hundred-megabyte files directly to git.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why save a Pipeline (scaler + model) instead of only the model?

    The saved pipeline carries the fitted scaler, so predictions in the app are consistent with training.
  2. 2. Which is the safest source for a model file you load with joblib?

    joblib and pickle can run arbitrary code on load. Only load files you trust.
  3. 3. How do you give one user a retrained model without changing it for others?

    Session state is per user, so the retrained model stays private to that session.
  4. 4. Why record sklearn_version in the model metadata?

    A mismatch between training and serving versions can fail or give subtly different results, so check it at load time.

Summary

  • Train offline and save with joblib.dump; the app only loads with joblib.load inside @st.cache_resource.
  • Save the whole pipeline plus metadata (features, classes, score, library version, hash).
  • Pin library versions and version your model files so you can roll back.
  • Never load untrusted pickles; verify a checksum for files you download.
  • Retrain on demand only from an explicit button, per session, and run long training as a background job.

Next: Model Evaluation Dashboards