coremltools: converting PyTorch, TensorFlow and scikit-learn models to Core ML

The gap coremltools fills between a training run and an app bundle

A trained model is a checkpoint. An app is a binary that has to run on a phone. Between those two points sits a format problem: Core ML reads .mlmodel files, and no training framework writes them. coremltools is the converter. The README lists the sources it accepts: TensorFlow 1.x, TensorFlow 2.x, PyTorch, and the non-neural frameworks scikit-learn, XGBoost and LibSVM. The audience is narrow and specific. It is an iOS, iPadOS, watchOS, macOS or tvOS developer who has a model that was trained somewhere else and now needs to run on device, inside Xcode, using Core ML APIs. The README frames the payoff in terms of on-device execution: Core ML schedules work across the CPU, GPU and Neural Engine and keeps the model off the network, which is what makes the privacy argument hold. If you never ship an Apple-platform app, the package has nothing to offer you.

What actually happens during a conversion

The package does not retrain anything. It walks the source model's graph, maps each operation onto the Core ML specification, and emits a serialised .mlmodel. The repository layout reflects that split. The mlmodel/ and modelpackage/ directories hold the format definitions, and the Core ML Specification is published as a separate reference, which is the document you read when a conversion fails and you need to know whether an operator exists in the target version at all. The README also lists a second job beyond conversion: reading, writing and optimising Core ML models. That matters because optimisation is a post-conversion step, applied to a model that is already in Core ML form. The third job, verifying conversion by making predictions through the Core ML framework, is the one with a platform constraint. The README qualifies it as on macOS. So the loop of convert, check, adjust runs on a Mac, while the conversion step itself is a Python operation you can script anywhere the package installs.

Installing coremltools and converting a model for the first time

The README gives a single install line and points at PyPI for the stable release. Use pip or whichever Python package manager you prefer.

pip install coremltools

After that, `import coremltools` should succeed and the package version should match the release you installed. The README also documents a dev channel, which installs a pre-release build rather than the stable one:

pip install coremltools==9.1.dev1

Treat that pin as a moving target. It is a development release, so pinning it in a shared environment means your builds change whenever a new dev wheel is published.

For a first real conversion, the README's framing is that you take a trained model from one of the supported libraries and produce a Core ML model. The package exposes a converter per source framework, and the API Reference is where the exact entry point for your framework lives. The repository ships an examples/ directory with its own README, which is the place to look for a worked case rather than guessing at arguments. Once a model is converted, the README's stated next step is Xcode: you add the .mlmodel to the app target and call it through Core ML APIs. The verification path, making predictions to confirm the conversion, is documented as macOS only, so plan to do that check on a Mac before you trust the output.

Where conversions break, and why the source framework matters

Conversion is a translation, and translations lose things. The supported-source list is the first constraint: TensorFlow 1.x, TensorFlow 2.x, PyTorch, scikit-learn, XGBoost and LibSVM. A model built on something outside that list has no documented path in. The second constraint is the operator set. A converted model is valid only against a Core ML specification version, and a model that uses an operation the target specification does not define will not convert cleanly. That is why the specification is published separately and why the README links it alongside the API Reference: the specification is the ground truth for what the format can express. The third constraint is the verification platform. The README states that prediction-based verification happens on macOS. On Linux you can install the package and run conversions, but you cannot close the loop by checking that the converted model produces the same answers as the original. That is a real gap for anyone whose CI runs on Linux containers, and it means a conversion pipeline that looks green in CI can still be wrong on device.

coremltools against a portable runtime like ONNX Runtime

The honest alternative is not another Core ML converter, because there is no second supported one. It is a portable runtime. ONNX Runtime takes a model in ONNX form and executes it across platforms and hardware backends, including non-Apple ones. The difference in approach is the whole point. coremltools targets one format and one vendor's execution stack, and in exchange it reaches the Neural Engine and integrates directly with Xcode and the Core ML APIs. ONNX Runtime targets portability, and in exchange it does not give you a .mlmodel that an Apple app can load natively. If your deployment includes an Android build, a Linux inference service, or a browser, one model and one runtime is a simpler story than maintaining a Core ML copy for Apple platforms and something else everywhere else. If Apple platforms are the only target, the portability argument buys you nothing and the Neural Engine argument is the one that decides it. Note also that coremltools lists neither ONNX nor ONNX Runtime among its supported sources, so an ONNX model is not a documented input here.

Versioning, licence and the cost of staying current

The package is released as versioned wheels on PyPI, with a stable line and a dev line running in parallel. The README's install examples show both, and the dev pin is a specific pre-release version rather than a floating tag. That structure tells you what upgrading costs: you move between discrete releases, and a release can change what the converter accepts. The repository ships a release notes link, which is the document to read before bumping the pin in a production pipeline.

The licence is BSD-3-Clause, stated in the repository and in the LICENSE.txt file, with the setup.py header pointing at the same identifier. That is a permissive licence, which in practice means you can redistribute the package and build it into your own tooling subject to the notice requirements. It says nothing about the models you produce or about Apple's frameworks, which are governed separately. This is a description of what the repository states, not legal advice; if the licence terms matter to your product, read LICENSE.txt and NOTICE.txt and get your own answer.

Building from source is a separate and heavier path. The repository carries a BUILDING.md, a CMakeLists.txt, a Makefile and a docker/ directory, and the Makefile's own comment says the Python environment must be set up before invoking make. That is a build system for contributors and for platforms without a wheel, not a step an application developer needs.

Who should adopt coremltools, and what to check first

Adopt it when the model trains outside Apple's stack and the deployment target is an Apple device. The supported sources cover the common cases: PyTorch, both TensorFlow lines, and the classical libraries scikit-learn, XGBoost and LibSVM for tabular and tree-based work. The README's own summary of the workflow is convert, then read, write and optimise, then verify on macOS, then integrate through Xcode. That sequence is the adoption plan.

Do not adopt it as a general model-serving tool. It does not run a server, it does not target non-Apple hardware, and its verification step is tied to macOS. If your inference happens in a Linux container, this is the wrong package and a portable runtime is the right one.

The thing to verify first is not the install. It is whether your specific model survives conversion. Check the operator coverage against the Core ML specification version you intend to target, run the conversion, and then run the prediction check on a Mac against your source framework's outputs on identical inputs. If that comparison holds, the rest of the pipeline is packaging.

Editorial conclusion

Adopt coremltools if you ship an iOS, iPadOS, watchOS, macOS or tvOS app and your model already trains outside Apple's stack. Do not adopt it if you need to run inference on Linux servers, or if you expect a conversion that needs no manual graph surgery. Before committing, verify three things on your own model: that your operators survive the conversion, that the target iOS version you support accepts the produced .mlmodel, and that predictions from the converted model match your source framework on the same inputs. The README points at the Installing Core ML Tools guide and the API Reference for the parts it does not spell out itself.

Frequently asked questions

Official sources

1. apple/coremltools on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases