🧪 ml2json

A safe, transparent way to export fitted scikit-learn (and friends) models to plain JSON, so you can share or deploy predictive models with peace of mind — no Pickle, no arbitrary code execution on load.

This is the continuation of the work originally hosted at OlivierBeq/sklearn-json.

✨ Features

• 🛡️ Safe — models are serialized to 100% JSON, which cannot execute code on deserialization, unlike Pickle or Joblib.
• 🔍 Transparent — model files are plain text, not binary, so you can always inspect exactly what's inside.
• 🔁 Round-trip faithful — deserialized models reproduce the same predict/transform/fit_predict output as the original, fitted estimator.
• 📦 290+ estimators supported across scikit-learn and 12 companion libraries (XGBoost, LightGBM, CatBoost, imbalanced-learn, HDBSCAN, UMAP, Prince, MLChemAD, openTSNE, and more) — see the compatibility matrix below.
• 🧩 Composable — Pipeline, ColumnTransformer, VotingClassifier/Regressor, StackingClassifier/Regressor and other meta-estimators are serialized recursively, nested estimators included.
• 🌍 Portable — JSON files are not tied to a Python or scikit-learn version the way Pickle/Joblib binaries are.

✍️ Why ml2json?

Other methods for exporting scikit-learn models rely on Pickle or Joblib (itself built on Pickle):

• Pickle is unsafe. Deserializing a Pickle file can execute arbitrary code, making it a straightforward attack vector for anyone who can get a malicious file loaded — see this write-up for an example.
• Pickle/Joblib are not portable. Their internal binary format is not guaranteed to be compatible across Python or library versions.

ml2json avoids both problems by serializing exclusively to JSON: human-readable, machine-readable, and safe to load from an untrusted source.

📦 Installation

pip install ml2json

Or from source:

git clone https://github.com/OlivierBeq/ml2json.git
pip install ./ml2json

🛠️ Requirements

• Python 3.11+
• scikit-learn >= 1.4.0

💡 Usage

Basic example

import ml2json
from sklearn.ensemble import RandomForestClassifier

model = RandomForestClassifier(n_estimators=10, max_depth=5, random_state=0).fit(X, y)

ml2json.to_json(model, file_name)
deserialized_model = ml2json.from_json(file_name)

deserialized_model.predict(X)

In-memory (dict) round-trip

Skip the file entirely and work with a plain, JSON-safe dict — useful for storing a model alongside other metadata (e.g. in a database document) instead of a standalone file:

model_dict = ml2json.to_dict(model)
deserialized_model = ml2json.from_dict(model_dict)

Pipelines and nested estimators

Pipeline, ColumnTransformer and ensemble meta-estimators (VotingClassifier, StackingRegressor, etc.) are serialized recursively — every nested, fitted estimator is preserved:

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression

pipeline = Pipeline([
    ("scaler", StandardScaler()),
    ("classifier", LogisticRegression()),
]).fit(X, y)

ml2json.to_json(pipeline, "pipeline.json")
deserialized_pipeline = ml2json.from_json("pipeline.json")

CatBoost models

CatBoost stores some information (e.g. categorical feature values) on the training Pool rather than on the fitted model itself. Pass it explicitly to recover it on serialization:

ml2json.to_json(catboost_model, "model.json", catboost_data=train_pool)

📚 API Documentation

def to_json(model, outfile, catboost_data=None):
def from_json(infile):

Serialize a fitted (or unfitted) model to/from a JSON file.

• model — the scikit-learn-compatible estimator to serialize.
• outfile / infile — path of the JSON file to write to / read from.
• catboost_data — optional catboost.Pool used to train model, required to recover certain CatBoost-specific attributes.

def to_dict(model, catboost_data=None):
def from_dict(model_dict):

Equivalent to to_json/from_json, but round-trips through an in-memory, JSON-safe dict instead of a file.

def dict_to_json(model_dict, outfile):
def json_to_dict(infile):

Lower-level helpers to write an already-serialized dict to a JSON file, or read one back, without touching the model itself.

🧬 Supported models

ml2json supports scikit-learn as well as the following companion libraries:

• scikit-learn-extra
• XGBoost
• LightGBM
• CatBoost
• Imbalanced-learn
• kmodes
• HDBSCAN
• UMAP
• PyNNDescent
• Prince
• MLChemAD
• openTSNE

The list of supported models is rapidly growing — if something you need is missing, please open an issue.

✍️ Attribution

ml2json is the continuation of OlivierBeq/sklearn-json, originally authored by Mathieu Rodrigue.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.