skops

skops is a Python library that solves two problems teams hit when they move scikit-learn models toward production: how to save and load a trained estimator without trusting pickle, and how to document that model so it can be shared, reviewed, or published responsibly. Its skops.io module implements a persistence format built around an explicit, type-audited state tree instead of executing arbitrary bytecode on load, so loading a model file can’t run attacker-controlled code the way unpickling can.

The companion skops.card module generates a Model Card — a structured Markdown document describing what the model does, how it was trained, and how it should be used — which can be dropped straight into a Hugging Face Hub repository’s README with pre-populated metadata the Hub understands. Together the two pieces cover persistence and documentation for the same object: an estimator that started life in a Jupyter notebook and now needs to leave it safely.

What You Get

• skops.io.dump/skops.io.load — save and load estimators to a zip-based file format without invoking pickle’s bytecode execution
• An explicit trust-audit step (get_untrusted_types, load(..., trusted=[...])) that requires the caller to acknowledge exactly which non-default types a file contains before it will load
• skops.card.Card — generates a Hugging Face-style Model Card in Markdown with pre-populated metadata sections (metrics, hyperparameters, evaluation results)
• A skops CLI (skops convert) for converting existing pickle files into the skops persistence format
• Type coverage for the numpy, scipy, and scikit-learn object graphs an estimator typically pulls in, plus optional support for quantile-forest models
• Read-the-Docs documentation with a persistence guide, model card guide, and runnable examples

Common Use Cases

• Publishing a trained scikit-learn model to the Hugging Face Hub with an auto-generated Model Card instead of hand-writing one
• Replacing pickle in an MLOps pipeline where model artifacts move between services or are loaded from untrusted or semi-trusted storage
• Migrating a codebase’s existing pickled models to the skops format via the skops convert CLI
• Producing model documentation (hyperparameters, metrics, evaluation plots) as part of a model-release checklist

Under The Hood

Architecture The library is organized as two largely independent subsystems under a shared skops/ package: skops.io for persistence and skops.card for documentation, plus a thin skops.cli wrapping both for command-line use. Persistence works by building an explicit “tree of nodes” (skops/io/_audit.py, _general.py, _numpy.py, _scipy.py, _sklearn.py) rather than deserializing directly: dump() (in _persist.py) walks an object via singledispatch get_state() functions registered per-type into a JSON schema.json plus a zip of binary buffers, and load() reconstructs it by walking a matching Node hierarchy through get_tree()/construct(), auditing every node’s (module, class) pair against a caller-supplied or default-trusted list before any object is instantiated. This node-tree indirection is the core abstraction — swapping it for direct unpickling would remove the entire security model the project exists to provide. skops.card is a separate templating/parsing layer (_model_card.py, _templates.py, _parser.py) that composes a Jinja-style Markdown document from metadata dictionaries, decoupled from the persistence code.

Tech Stack Pure Python (99.97% of the repo), targeting Python 3.9–3.14, built with the hatchling backend and a dynamic version sourced from skops/__init__.py. Runtime dependencies are numpy>=1.25, scipy>=1.10, scikit-learn>=1.2, prettytable>=3.9, and packaging>=17.0, with an optional rich extra for nicer CLI output; there are no web/ORM framework dependencies since this is a library, not a service. CI runs against a matrix of scikit-learn versions (1.2 through nightly) across Windows, macOS, and Linux via GitHub Actions, and the project also maintains a pixi.lock/pyproject.toml conda-forge environment definition alongside the standard PyPI packaging path — evidence of deliberate attention to cross-platform numerical-stack compatibility.

Code Quality The project has an extensive test suite (over 200 test_*.py functions) run with pytest, including --doctest-modules so docstring examples are themselves executed as tests, and coverage is tracked via Codecov. Code is formatted with Black and linted with Ruff (E, F, W, I rule sets), type-checked with mypy (with narrow, explicit excludes for test files and legacy code), and enforced through pre-commit. Errors are handled explicitly and deliberately — the custom UntrustedTypesFoundException and UnsupportedTypeException are raised rather than swallowed, matching a library whose entire purpose is refusing to proceed silently on unsafe input. CI runs on every push and PR across the full OS/sklearn-version matrix, which is comprehensive for a library with this large a compatibility surface.

What Makes It Unique Most “secure pickle alternative” tools for ML either restrict to a narrow safe subset of types or require rewriting models in a different serialization format entirely. skops instead keeps scikit-learn’s native object graph but replaces pickle’s implicit bytecode execution with an explicit, inspectable node tree that the caller must audit and trust type-by-type before it constructs anything — persistence and security review become the same step rather than a separate scanning pass bolted onto pickle. Pairing that with an integrated Model Card generator aimed specifically at the Hugging Face Hub’s metadata schema is also a distinctive combination: most persistence libraries stop at serialization and leave documentation to the user.