{"id":3436,"library":"coremltools","title":"Core ML Tools","description":"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.","status":"active","version":"9.0","language":"en","source_language":"en","source_url":"https://github.com/apple/coremltools","tags":["machine-learning","model-conversion","apple","coreml","pytorch","tensorflow","scikit-learn","xgboost","libsvm"],"install":[{"cmd":"pip install coremltools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required 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.","package":"torch","optional":true},{"reason":"Required for converting TensorFlow/Keras models.","package":"tensorflow","optional":true},{"reason":"Core library dependency, often needs to be a compatible version, e.g., numpy 2.0 is supported in coremltools 8.0.","package":"numpy","optional":false},{"reason":"Crucial for model serialization; coremltools 8.0 requires a compatible, often newer, protobuf version for improved latency.","package":"protobuf","optional":false},{"reason":"Required for converting scikit-learn models. Compatibility with scikit-learn 1.5 is supported in coremltools 8.0.","package":"scikit-learn","optional":true}],"imports":[{"symbol":"coremltools","correct":"import coremltools as ct"},{"symbol":"ct.convert","correct":"mlmodel = ct.convert(model=pytorch_model, inputs=[ct.TensorType(shape=input_shape)])"},{"note":"Input types should be explicitly defined using `ct.TensorType` or `ct.ImageType` for correct shape and preprocessing handling, not raw tuples.","wrong":"inputs=[(3, 224, 224)]","symbol":"ct.TensorType","correct":"inputs=[ct.TensorType(shape=(1, 3, 224, 224))]"}],"quickstart":{"code":"import coremltools as ct\nimport torch\nimport torchvision\n\n# 1. Define a PyTorch model\nmodel = torchvision.models.mobilenet_v2(pretrained=True)\nmodel.eval()\n\n# 2. Create a dummy input for tracing\nexample_input = torch.rand(1, 3, 224, 224)\n\n# 3. Trace the model (or use torch.export in newer PyTorch/coremltools versions)\ntraced_model = torch.jit.trace(model, example_input)\n\n# 4. Convert the traced model to Core ML format\n# Specify inputs explicitly for correct type and shape handling\n# For image inputs, use ct.ImageType with appropriate preprocessing parameters\nmlmodel = ct.convert(\n    traced_model,\n    inputs=[\n        ct.ImageType(name=\"input_1\", shape=example_input.shape, scale=1/255.0, bias=, channel_first=True)\n    ],\n    convert_to='mlprogram',\n    minimum_deployment_target='iOS16'\n)\n\n# 5. Save the Core ML model\nmlmodel.save(\"MobileNetV2.mlpackage\")\nprint(\"Model converted and saved as MobileNetV2.mlpackage\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"4.0 and newer"},{"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.","message":"Core ML Tools 5.0 introduced the `.mlpackage` directory format for Core ML models, replacing the older `.mlmodel` protobuf file format.","severity":"breaking","affected_versions":"5.0 and newer"},{"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`.","message":"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.","severity":"breaking","affected_versions":"8.0 and newer"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"8.0 and newer"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}