{"id":4259,"library":"skl2onnx","title":"skl2onnx: Convert Scikit-learn Models to ONNX","description":"skl2onnx is a Python library that enables the conversion of scikit-learn machine learning models and pipelines into the ONNX (Open Neural Network Exchange) format. This conversion allows for improved model portability across different runtimes and often leads to enhanced inference performance, especially with ONNX Runtime. The library is actively maintained with frequent releases, typically on a monthly or bi-monthly cadence, and is currently at version 1.20.0.","status":"active","version":"1.20.0","language":"en","source_language":"en","source_url":"https://github.com/onnx/sklearn-onnx","tags":["machine learning","model conversion","onnx","scikit-learn","inference"],"install":[{"cmd":"pip install skl2onnx onnx onnxruntime","lang":"bash","label":"Install core packages"}],"dependencies":[{"reason":"Required for the scikit-learn models that skl2onnx converts. Recent versions of skl2onnx (>=1.17.0) are tested with scikit-learn versions >= 1.1.","package":"scikit-learn","optional":false},{"reason":"The core ONNX format definition and tools, fundamental for creating ONNX models.","package":"onnx","optional":false},{"reason":"A high-performance inference engine for ONNX models, commonly used to run converted models and for testing skl2onnx converters.","package":"onnxruntime","optional":false},{"reason":"Often implicitly required by scikit-learn and for handling data types during ONNX conversion.","package":"numpy","optional":false}],"imports":[{"note":"This is the primary function for converting a scikit-learn model, automatically inferring input types from example data.","symbol":"to_onnx","correct":"from skl2onnx import to_onnx"},{"note":"This function provides more explicit control over conversion, requiring 'initial_types' to be specified manually.","symbol":"convert_sklearn","correct":"from skl2onnx import convert_sklearn"},{"note":"Essential for defining input data types, especially when using 'convert_sklearn'.","symbol":"FloatTensorType","correct":"from skl2onnx.common.data_types import FloatTensorType"}],"quickstart":{"code":"import numpy as np\nfrom sklearn.datasets import load_iris\nfrom sklearn.ensemble import RandomForestClassifier\nfrom skl2onnx import to_onnx\nimport onnxruntime as rt\n\n# 1. Train a scikit-learn model\niris = load_iris()\nX, y = iris.data, iris.target\nX = X.astype(np.float32) # ONNX typically uses float32\nmodel = RandomForestClassifier(n_estimators=10, random_state=42)\nmodel.fit(X, y)\n\n# 2. Convert the scikit-learn model to ONNX format\n# `X[:1]` is used to infer the input types and shapes\nonx_model = to_onnx(model, X[:1])\n\n# 3. Save the ONNX model to a file\nwith open(\"rf_iris.onnx\", \"wb\") as f:\n    f.write(onx_model.SerializeToString())\n\n# 4. Load and make predictions with ONNX Runtime\nsess = rt.InferenceSession(\"rf_iris.onnx\", providers=[\"CPUExecutionProvider\"])\ninput_name = sess.get_inputs()[0].name\noutput_names = [output.name for output in sess.get_outputs()]\n\n# Make a prediction\npredictions = sess.run(output_names, {input_name: X[0:1].astype(np.float32)})\n\nprint(f\"Original model prediction: {model.predict(X[0:1])}\")\nprint(f\"ONNX Runtime prediction (label): {predictions[0]}\")\nprint(f\"ONNX Runtime prediction (probabilities): {predictions[1]}\")","lang":"python","description":"This quickstart demonstrates how to train a simple RandomForestClassifier from scikit-learn, convert it to the ONNX format using `skl2onnx.to_onnx`, save the ONNX model to a file, and then load it with ONNX Runtime for inference. It highlights the typical workflow from training to ONNX-based prediction."},"warnings":[{"fix":"Install `skl2onnx==1.19.1` or a more recent version like `pip install skl2onnx`.","message":"Version 1.19.0.1 (released as 0.19.0 on PyPI) was incomplete. Users attempting to install or use this specific version should instead use 1.19.1 or later to avoid issues.","severity":"breaking","affected_versions":"1.19.0.1"},{"fix":"Ensure your scikit-learn installation is up-to-date, preferably `scikit-learn>=1.1`, to maintain compatibility and receive tested support.","message":"The minimum supported version of scikit-learn has increased over time. As of skl2onnx 1.17.0, older scikit-learn versions (<1.1) are no longer tested, and prior to 1.16.0, versions < 1.0 were not tested.","severity":"breaking","affected_versions":">=1.16.0"},{"fix":"Review your custom converter implementations and update them to use `skl2onnx`'s internal utilities or directly depend on `onnxconverter-common` if still needed for other purposes.","message":"The `onnxconverter-common` dependency was removed in skl2onnx version 1.19.1. If you had custom converters or logic relying directly on components from this library through skl2onnx, you will need to update your code.","severity":"deprecated","affected_versions":">=1.19.1"},{"fix":"Always pass a small sample of your input data (e.g., `X[:1]`) to `to_onnx` for inference, or explicitly define `initial_types` (e.g., `[('input', FloatTensorType([None, n_features]))]`) for `convert_sklearn`.","message":"When converting a model using `convert_sklearn`, you must provide `initial_types` to define the input schema (names, types, and shapes). Failing to do so or providing incorrect types will lead to conversion errors. While `to_onnx` can infer this from sample data (e.g., `X[:1]`), understanding expected input types is crucial for robust conversions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `target_opset=N` (e.g., `target_opset=22`) to your `to_onnx` or `convert_sklearn` call, aligning with your ONNX Runtime version's capabilities.","message":"Specify the `target_opset` parameter during conversion for better compatibility. While skl2onnx will choose the latest tested opset if not specified, it's recommended to set it explicitly (e.g., `target_opset=14` or higher for broader compatibility with modern ONNX Runtimes). skl2onnx 1.17.0 supports up to opset 21, and 1.20.0 up to opset 22.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass `options={id(model): {'zipmap': False}}` to your `to_onnx` or `convert_sklearn` call to disable ZipMap output for classification models if needed.","message":"For classification models, the output includes probabilities in a 'ZipMap' format by default, which might not be universally supported or desired for all deployment targets. Some platforms (e.g., BigQuery ML) require disabling this feature.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the `skl2onnx` documentation's 'Supported scikit-learn Models' and 'Advanced scenarios' sections for a comprehensive list of supported models and known limitations, especially regarding sparse inputs or complex transformers.","message":"skl2onnx has limitations on certain scikit-learn features and models. Sparse data support is limited, and models that perform iterative numerical optimization during inference (like NMF or LDA) are generally not supported for conversion.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}