Core ML Tools

9.0 · active · verified Sat Apr 11

Core ML Tools is an open-source Python package developed by Apple for converting, optimizing, and validating machine learning models into Apple's Core ML format. It supports models from popular frameworks like TensorFlow, PyTorch, scikit-learn, XGBoost, and LibSVM. The library is actively maintained, with frequent releases, and is currently at version 9.0, adding support for Python 3.13, PyTorch 2.7, and new iOS/macOS deployment targets.

Warnings

breaking Core ML Tools 4.0 introduced the Unified Conversion API (`ct.convert`). Older converters like `onnx-coreml` (for PyTorch) and `coremltools.keras.convert` (for Keras/TF1) are no longer maintained or officially deprecated.
Fix: Migrate your conversion workflows to use the `coremltools.convert` API. For PyTorch, convert directly without an intermediate ONNX step. For Keras/TensorFlow, use the TF2 backend with `ct.convert`.
breaking Core ML Tools 5.0 introduced the `.mlpackage` directory format for Core ML models, replacing the older `.mlmodel` protobuf file format.
Fix: Ensure your tools and Xcode versions are compatible with the `.mlpackage` format. The `mlmodel.save()` method will automatically save in the new format by default.
breaking coremltools 8.0 updated its dependency compatibility, requiring a newer `protobuf` Python package version. Incompatible `protobuf` versions can lead to serialization errors or conversion failures.
Fix: Ensure your `protobuf` package is up-to-date and compatible with `coremltools` 8.0+. Check `coremltools` release notes for specific version requirements of `protobuf`, `torch`, `numpy`, and `scikit-learn`.
gotcha Incorrect image preprocessing parameters during conversion (e.g., `scale`, `bias`, `is_bgr`) are a common cause of wrong predictions on device. Models expect specific normalization, pixel ranges (0-1, -1 to 1), and channel order (RGB vs BGR).
Fix: Carefully review the training pipeline of your source model and ensure the `ct.ImageType` parameters (e.g., `scale`, `bias`, `red_bias`, `green_bias`, `blue_bias`, `is_bgr`, `channel_first`) exactly match the preprocessing used during training.
gotcha While coremltools supports flexible input shapes, using `EnumeratedShapes` or `RangeDim` can impact performance. Models with fully dynamic shapes or `RangeDim` might not fully utilize the Apple Neural Engine (ANE) for acceleration.
Fix: For optimal ANE performance, use `EnumeratedShapes` with a limited, predetermined set of input shapes when possible. If more flexibility is needed, use `RangeDim` but be aware of potential performance tradeoffs and ANE limitations.
gotcha When converting PyTorch models, `torch.jit.trace` is currently the stable and generally more performant path. `torch.export` is newer (introduced in coremltools 8.0) and is still in beta, mirroring its status in PyTorch.
Fix: For production and critical workloads, `torch.jit.trace` is recommended. Experiment with `torch.export` for newer models or specific features, but be prepared for potential issues or performance regressions, and report them on GitHub.

Install

pip install coremltools Install stable version

Imports

coremltools
```
import coremltools as ct
```

ct.convert

mlmodel = ct.convert(model=pytorch_model, inputs=[ct.TensorType(shape=input_shape)])

ct.TensorType
```
inputs=[ct.TensorType(shape=(1, 3, 224, 224))]
```
Input types should be explicitly defined using `ct.TensorType` or `ct.ImageType` for correct shape and preprocessing handling, not raw tuples.

Quickstart

This quickstart demonstrates how to convert a pre-trained PyTorch MobileNetV2 model to the Core ML format using `coremltools`. It involves defining a PyTorch model, tracing it with a dummy input, and then using `ct.convert` to generate the `.mlpackage` file. Explicitly defining input types and preprocessing parameters is crucial for correct conversion.

import coremltools as ct
import torch
import torchvision

# 1. Define a PyTorch model
model = torchvision.models.mobilenet_v2(pretrained=True)
model.eval()

# 2. Create a dummy input for tracing
example_input = torch.rand(1, 3, 224, 224)

# 3. Trace the model (or use torch.export in newer PyTorch/coremltools versions)
traced_model = torch.jit.trace(model, example_input)

# 4. Convert the traced model to Core ML format
# Specify inputs explicitly for correct type and shape handling
# For image inputs, use ct.ImageType with appropriate preprocessing parameters
mlmodel = ct.convert(
    traced_model,
    inputs=[
        ct.ImageType(name="input_1", shape=example_input.shape, scale=1/255.0, bias=, channel_first=True)
    ],
    convert_to='mlprogram',
    minimum_deployment_target='iOS16'
)

# 5. Save the Core ML model
mlmodel.save("MobileNetV2.mlpackage")
print("Model converted and saved as MobileNetV2.mlpackage")

view raw JSON →