coremltools

library9.0pypypi✓ verified 24d ago

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.

ai-ml devops

pip install coremltools

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COREMLTOOLS

coremltools

ai-mlpythonv9.0

Install

10.8s avg

Import

3630ms

Disk

194MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 4.112s · 178MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 10.8s · import 3.148s · 175MB

194MB installed

● package 194MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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))]

✗ inputs=[(3, 224, 224)]

Input types should be explicitly defined using `ct.TensorType` or `ct.ImageType` for correct shape and preprocessing handling, not raw tuples.

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")

coremltools --version

Debug

Known issues

breakingCore 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`.

affects: 4.0 and newer

breakingCore 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.

affects: 5.0 and newer

breakingcoremltools 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`.

affects: 8.0 and newer

gotchaIncorrect 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.

affects: All versions

gotchaWhile 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.

affects: All versions

gotchaWhen 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.

affects: 8.0 and newer

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'coremltools'

The 'coremltools' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install coremltools'.

ImportError: cannot import name 'ParametricSoftPlus'

The 'ParametricSoftPlus' activation function is not available in the installed version of Keras.

fix

Ensure that the Keras version supports 'ParametricSoftPlus' or replace it with a supported activation function.

Failed to load _MLModelProxy: No module named 'coremltools.libcoremlpython'

The 'coremltools.libcoremlpython' module is missing, possibly due to an incomplete installation.

fix

Reinstall 'coremltools' ensuring all dependencies are correctly installed: 'pip install --force-reinstall coremltools'.

ImportError: cannot import name 'convert'

The 'convert' function is not directly importable from 'coremltools' due to changes in the library's structure.

fix

Use the unified conversion API: 'import coremltools as ct; ct.convert(...)'.

ValueError: In op, of type [X], named [Y], the named input [Z] must have the same data type as the named input x. However, [Z] has dtype fp32 whereas x has dtype fp16.

A data type mismatch occurs during model conversion, often due to mixed precision between FP32 and FP16.

fix

Ensure the PyTorch model is in FP32 before conversion; the model will be converted to FP16 during the Core ML conversion process unless specified otherwise.

Upgrade

Version history

9.0latest on PyPI · released Nov 10, 2025

Audit

Dependencies

torchoptionalRequired for converting PyTorch models. Compatibility with specific PyTorch versions is critical for successful conversion, e.g., PyTorch 2.7 is supported in coremltools 9.0.

tensorflowoptionalRequired for converting TensorFlow/Keras models.

numpyrequiredCore library dependency, often needs to be a compatible version, e.g., numpy 2.0 is supported in coremltools 8.0.

protobufrequiredCrucial for model serialization; coremltools 8.0 requires a compatible, often newer, protobuf version for improved latency.

scikit-learnoptionalRequired for converting scikit-learn models. Compatibility with scikit-learn 1.5 is supported in coremltools 8.0.

Agent activity

47 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/apple/coremltools ↗

packagehttps://pypi.org/project/coremltools/ ↗

homepagehttps://apple.github.io/coremltools/ ↗