mlmodel — what it is, file structure and conversion to mlpackage

What is mlmodel?

mlmodel is a binary file format introduced by Apple in 2017 alongside the Core ML framework at WWDC 2017. The format is based on Google’s protobuf (Protocol Buffers) serialization technology, which ensured compact size (model weights in Float32) and efficient memory loading. The .mlmodel file had a .mlmodel extension and MIME type application/x-Apple-mlmodel.

History of the format

The .mlmodel format was the only Core ML format from 2017 to 2021. During this time, millions of models from TensorFlow, Keras, PyTorch, Caffe, scikit-learn, and other libraries were converted via coremltools. The format’s limitations became evident as model complexity grew: protobuf does not support convenient versioning, metadata is stored in binary form (unreadable in git diff), and adding new fields required changes to the protobuf schema.

Key characteristics

The mlmodel file stores the model in a compact binary representation. Size ranges from tens of kilobytes (linear regression) to gigabytes (neural networks with millions of parameters). The format supports all Core ML model types: neural networks (NeuralNetwork, NeuralNetworkClassifier, NeuralNetworkRegressor), ensemble models (TreeEnsemble, GradientBoosting), regressions (LinearRegression, SVM), and pre/post-processing pipelines (OneHotEncoder, FeatureVectorizer).

Structure of the mlmodel file

The internal structure of the .mlmodel file is defined by a protobuf schema described in the CoreML.framework framework. The main sections are: modelDescription — description of inputs, outputs, and model metadata; modelParameters — specific parameters of the model type (neural network weights, tree ensembles, regression coefficients); preprocessing — preprocessing configuration (scaling, image normalization); postprocessing — post-processing (softmax, argmax, threshold values).

The modelDescription section

The modelDescription section (MLModelDescription) contains the model name, author, version, description, license, and a detailed description of all input and output parameters: name, data type (Float32, Int32, String, Image), dimensionality, image format (BGR, RGB), and optional constraints (value range). This section was used by Xcode to generate a Swift model class with typed inputs and outputs.

The modelParameters section

The modelParameters section contains the actual weights and parameters of the trained model. For neural networks, this is an array of layers (NeuralNetworkLayer), each containing the type (convolution, pooling, activation, innerProduct), weights, bias, and parameters (kernelSize, stride, padding). For ensemble models — decision trees and their nodes. For regressions — coefficients and intercept. Weights are stored in Float32 (4 bytes per value).

The preprocessing section

The preprocessing section describes the steps for preprocessing input data before feeding it into the model. Core ML supports: scaling (Scaler) — normalization via mean and standard deviation; image transformation (ImagePreprocessing) — resizing, cropping, color channel normalization, BGR→RGB conversion; OneHotEncoder — encoding categorical features; FeatureVectorizer — combining multiple features into a single vector.

mlmodel vs mlpackage: comparative analysis

mlpackage is a next-generation format for Core ML models, introduced at WWDC 2021. Unlike the single binary .mlmodel file, .mlpackage is a directory (package) with a file structure: model content is stored as readable JSON files (metadata, layer configuration) and separate binary files for weights. This fundamentally changes the approach to storage, versioning, and collaboration on ML models.

File structure of mlpackage

The .mlpackage package contains: ModelCI/ — directory with versioned model configuration; Data/ — binary weight files (SharedWeights.bin); Metadata.json — name, author, description, model version, creation date; Model.json — architecture description, inputs/outputs, layer types; Manifests/ — version manifests for CI/CD. This structure allows efficient work with the model in git: metadata and configuration are tracked, while binary weights can use Git LFS.

How to convert mlmodel to mlpackage

Conversion from .mlmodel to .mlpackage is done in two ways: automatically during Xcode build (Xcode itself converts .mlmodel to .mlpackage during compilation) or manually via coremltools in Python. Manual conversion gives more control and allows updating model metadata, adding a description, and setting the author. After conversion, the model is saved as .mlpackage and can be used instead of the original .mlmodel.

import coremltools as ct

model = ct.models.MLModel(
    "OldModel.mlmodel"
)
model.author = "IT Sectr"
model.short_description = "Converted from mlmodel"
model.version = "2.0"
model.save("NewModel.mlpackage")

Automatic conversion in Xcode

When adding a .mlmodel file to an Xcode project, the system automatically detects its format and during build launches the Model Compiler — a tool that translates .mlmodel into .mlpackage. The compiled .mlpackage is placed in the build directory (DerivedData). The developer does not notice this process — all Core ML APIs work with the model uniformly regardless of the original format. However, Xcode issues a warning when adding .mlmodel with a recommendation to use .mlpackage.

Verification after conversion

After conversion, it is necessary to ensure the model has preserved accuracy. coremltools provides the ct.utils.compare_models() utility for comparing predictions of the original and converted model on identical input data. The acceptable discrepancy is no more than 1e-5 for Float32. If the discrepancy exceeds this threshold, the model may have had custom layers or operations that are not supported in the new format.

Backward compatibility and support

Backward compatibility of .mlmodel is ensured on all current versions of iOS and macOS. An application compiled with Xcode 12 or newer automatically receives the .mlpackage version of the model, even if the original file was .mlmodel. However, starting with Xcode 15 (2023), Apple announced that new model types (dynamic neural networks, controlled learning) will only be available in .mlpackage format, and .mlmodel will not receive new capabilities.

Support in iOS 18+ and macOS 15+

Starting with iOS 18 and macOS 15 (Sequoia), Core ML no longer supports loading .mlmodel directly. All .mlmodel models must be pre-converted to .mlpackage, or the Xcode Model Compiler will be used for conversion during build. The system API MLModel(contentsOf:) can still open .mlmodel files only if they are converted to .mlpackage at the project build stage.

End-of-support timeline

Apple has not officially announced a date for complete removal of .mlmodel support, but the historical context suggests a 3–4 year transition period. The .mlmodel format was introduced in 2017, .mlpackage in 2021. Deprecation warnings appeared in Xcode 13 (2021). By analogy with 32-bit applications (iOS 11 dropped support), full .mlmodel support may be discontinued in iOS 20–21 (2026–2027).

When mlmodel is still relevant

Despite the format’s deprecation, .mlmodel is still found in existing projects and some scenarios. Developers working with Core ML need to understand when .mlmodel remains part of the workflow and how to properly interact with it without losing performance.

Legacy — old projects

Existing projects started before 2021 may contain dozens of .mlmodel models loaded via Swift Package Manager or directly in Xcode. Migrating all models to .mlpackage can be labor-intensive, especially if the models were generated by an older version of coremltools (pre-5.0). Apple recommends gradual migration, one model at a time, during the nearest functionality update.

CI/CD pipeline with coremltools

Some existing CI/CD pipelines use coremltools version 4.x for automatic model conversion, which by default exports to .mlmodel. Updating coremltools to version 5+ changes the export format to .mlpackage, which may require updating scripts and tests. In such cases, teams sometimes temporarily keep exporting to .mlmodel, planning migration for a later date.

Libraries and Pods

Third-party libraries and CocoaPods published before 2021 may contain models in .mlmodel format. For example, libraries for face recognition, image filtering, or AR filters. Developers using such libraries can continue working with .mlmodel since Xcode automatically converts them during build. However, it is recommended to check whether the author has released an update with .mlpackage.

Common mlmodel issues

When working with the deprecated .mlmodel format, developers encounter several common issues. Knowing these problems and their solutions helps avoid wasted time when integrating Core ML models into modern projects. Let’s look at the main ones.

Xcode deprecation warning

When adding .mlmodel in Xcode 13+, a warning appears: “‘mlmodel’ format is deprecated. Use ‘mlpackage’ instead.” The warning does not block the build but indicates the need for migration. To resolve the warning, convert the model via coremltools or update the model creation tool.

“Model file is not valid” error

A .mlmodel file created with an older version of coremltools (pre-3.0) may fail to open on new devices with iOS 16+ due to changes in protobuf codecs. The solution is to load the model through Python: model = ct.models.MLModel(“old.mlmodel”), then save it again: model.save(“fixed.mlmodel”), or better yet, convert it directly to .mlpackage.

Custom layer issues

Models .mlmodel containing custom layers (user-defined neural network layers) cannot be directly converted to .mlpackage without additional steps. You must first load the model in coremltools, check which layers are not supported by the new format, and implement them for .mlpackage. If the custom layer is not critical, you can try removing it from the model.