Create ML guide: App vs. framework, explained for devs

Updated Aug 24, 2026

Contents

Most Create ML confusion isn't about the ML, it's about which Create ML you're even using. Apple ships two things under that name: a standalone macOS app for point-and-click training, and a Swift framework for programmatic pipelines.

Picking the wrong one for your workflow means rebuilding your data pipeline halfway through a project. This guide separates the two clearly, then walks through labeling, augmenting, training, and exporting a real .mlmodel, with actual benchmark timings and the error messages you'll hit along the way.

If you're new to the broader AI model development process, start there for the wider context before diving into Create ML specifics.

What is create ML? App vs. Framework at a glance

The Create ML app and Create ML framework are separate products under one name. The app is a standalone macOS tool for training models through drag-and-drop; the framework is a Swift API (import CreateML) for scripting the same pipelines in code. Apple introduced both together at WWDC19's "Introducing Create ML" session.

Confusing the two costs time: the app has no CI hooks, the framework has no built-in confusion matrix view.

Building a multi-model demo app across image, text, and tabular classifiers, we needed both: the app for quick image runs, the framework's MLDataTable for tabular augmentation. Either path exports the same .mlmodel file for Core ML.

Create ML app vs. Create ML framework: Which One am I using?

The Create ML app fits quick, one-off model training when you need drag-and-drop simplicity and built-in metrics review. The Create ML framework fits repeatable pipelines you want under version control. Both export the same .mlmodel file for Core ML, so the choice comes down to workflow, not output quality.

Need	Create ML app	Create ML framework
Drag-and-drop training, no code	Yes	No
Scriptable, repeatable pipelines	No	Yes
Confusion matrix + metrics review	Built-in tab	Print manually via MLClassifierMetrics
Data augmentation controls	Sliders in UI	Set as `MLImageClassifier.ImageAugmentationOptions` in code
Runs in CI / automated batch jobs	No, GUI only	Yes, plain Swift executable
Version-controllable config	No	Yes

We default to the framework once a model needs retraining on new data monthly, since an automated training script checked into a repo beats re-clicking through a GUI each time. For a single image classifier prototype in Xcode, the app is faster to get a working .mlmodel in one afternoon.

Every property in that table traces back to the Apple Developer documentation page for Create ML, which is worth bookmarking since Apple updates augmentation options and API signatures with each OS release.

Neither option gives you the layer-level control TensorFlow or PyTorch offer for custom transfer learning architectures. Create ML trades that control for training times measured in minutes, not GPU-hours.

Getting started: Xcode and macOS requirements

The Create ML app ships inside Xcode itself: open Xcode, then Xcode > Open Developer Tool > Create ML, and you're training your first model with no separate download. Apple's Create ML developer documentation lists macOS Ventura (13) and Xcode 14 as the floor for the app, with Xcode 15+ needed for the newer transfer learning templates.

The framework runs on Intel Macs too, but GPU acceleration for training only kicks in on Apple Silicon. On an Intel machine, expect training runs to take noticeably longer, especially for image classifiers using data augmentation.

Labeling and preprocessing your training data

An image classifier in Create ML is only as good as its folder structure: one subfolder per label, images dropped in directly, no manifest file required.

Here's what that folder layout actually looks like on disk:

TrainingData/
├── cats/
│ ├── cat001.jpg
│ ├── cat002.jpg
│ └── cat003.jpg
└── dogs/
 ├── dog001.jpg
 ├── dog002.jpg
 └── dog003.jpg

Drag the TrainingData folder into the training data well, and Create ML reads each subfolder name as the class label automatically. The Create ML app then handles the training/validation split on its own, holding back roughly 20% of each label's images unless you supply a validation set yourself.

Getting that split and the label folders right up front avoids most of the errors we hit building a multi-model demo app.

How to label data in create ML

The Create ML app labels images by folder name, not by file name or metadata. No CSV or JSON manifest is required for image classifiers, the folder name is the entire labeling scheme.

This differs sharply from a TensorFlow or PyTorch pipeline, where you write a custom Dataset class and control every augmentation step. Create ML trades that control for speed: rename a folder, and every image in it relabels instantly.

Create ML JSON format for preprocessing

A text classifier or tabular classifier in Create ML does not read folder names. Both expect a flat JSON array of objects, each with a label key and one or more feature keys, as shown in the Apple Developer documentation:

[
 {"text": "Refund my order now", "label": "complaint"},
 {"text": "Thanks for the fast delivery", "label": "praise"}
]

CSV works too for tabular data, but JSON handles mixed types and nested feature columns without the encoding headaches.

One error we hit building a text classifier: a malformed array threw "The file couldn't be opened" with no line number. Running the file through jq first caught the stray comma Xcode's importer wouldn't point to.

How to augment data in create ML

Create ML's image classifier exposes data augmentation as a set of checkboxes in the training pane: rotation, blur, noise, crop, flip, and exposure. Each toggle synthesizes altered copies of your training images on the fly.

A 200-photo dataset trains as if it were several times larger without touching your source data.

Rotation and flip help most when your production photos arrive at unpredictable angles, phone camera shots of shelf products, for instance. Blur and noise simulate low-light or compressed-camera input. Crop guards against a classifier that has only ever seen centered subjects, forcing it to recognize partial or off-center views instead of memorizing a fixed frame.

For the full list of parameters each toggle controls, the Apple Developer documentation is worth a bookmark before you start a long training run.

Augmentation hurts when your validation set doesn't reflect the augmented distribution.

On one multi-model demo we built, turning on all five toggles for a 12-class product classifier pushed training accuracy up but dropped validation accuracy 6 points. Blur alone was the culprit.

The fix: enable toggles individually, retrain, and read the confusion matrix after each run before stacking them. This automated, one-at-a-time approach costs more training time but keeps you from shipping a model that only performs well on synthetic noise.

Training your first model (and why it's so fast)

Create ML trains its image classifier through transfer learning: it takes a feature extractor already trained on millions of images and only retrains the final classification layers on your dataset.

That is why a 200-photo set finishes in minutes rather than hours, with most of the heavy lifting automated behind the scenes.

On a base M2 MacBook Air, a three-class flower classifier with augmentation enabled trained in just under two minutes. The same project on a 2017 Intel MacBook Pro took closer to twelve. According to independent testing, an M1 MacBook Air trained an ML model in 11m 30s vs Intel MacBook Pro 16-inch in 43m+ (Mr. D. Bourke ML speed comparison blog, 2021).

When training finishes, Create ML opens straight into a confusion matrix per class on its results page, so you can spot which categories get confused before exporting the .mlmodel file into Xcode.

If any step feels unclear, the Apple Developer Documentation page for Create ML covers each parameter in more depth than this walkthrough allows.

Reading create ML's performance metrics

The Create ML app splits your dataset automatically, typically holding back 20% for validation while training on the rest, and the training/validation split you choose changes what the accuracy score actually means. A validation curve that lags training accuracy by more than a few points signals overfitting before you ever touch the confusion matrix.

The confusion matrix is where precision and recall stop being abstract. Each cell maps predicted label against true label: the diagonal is correct predictions, everything off-diagonal is where your classifier confuses two classes. High false positives in one column mean poor precision for that class; high false negatives in one row mean poor recall.

On our flower classifier, most misclassifications clustered in one row, which pointed to two visually similar species rather than a training bug.

This is also where Create ML's control tradeoff against TensorFlow or PyTorch shows up. You get the metrics view, not the loss curves or per-layer gradients, so debugging a stubborn row in the confusion matrix means adding more images or augmentation, not adjusting a learning rate.

Exporting and deploying your .mlmodel with core ML

Create ML writes out a .mlmodel file the moment training finishes, and dragging it into Xcode generates a Swift class with typed inputs and outputs automatically. No manual bridging code, no separate conversion step.

Core ML picks up the model's metadata (author, license, description) straight from what you filled in during training, so it is worth writing that metadata properly instead of leaving Xcode's defaults.

A multi-model demo app mixing an image classifier, a text classifier, and a tabular regressor in one Xcode project surfaces how differently each model type behaves once wired into a UIKit view versus a SwiftUI preview.

This is also where the Create ML versus TensorFlow/PyTorch tradeoff becomes concrete: you trade export flexibility for a one-click path straight into a shipping iOS build. If weighing that tradeoff feels overwhelming, partnering with an experienced software development team can help you decide which path fits your product roadmap.

Beyond images: Sound, activity, object detection, and create ML vs. TensorFlow

Create ML's template list beyond images covers sound classification, activity classification, object detection, and recommender model, each using the same transfer learning shortcut as the image classifier: a pretrained feature extractor plus your own labeled data.

The trade-off against TensorFlow or PyTorch is control versus speed. Create ML gets a working .mlmodel file in an afternoon; a custom PyTorch pipeline gives you architecture choices Create ML hides entirely. If you're weighing frameworks beyond Create ML, our guide comparing mobile ML frameworks breaks down Core ML against TensorFlow Lite in more detail.

Framework	Setup time	Architecture control	Export target
Create ML	Hours	Low (fixed templates)	Core ML native
TensorFlow/PyTorch	Days to weeks	Full	Needs Core ML Tools conversion
Netguru custom ML pipeline	Scoped to project	Full, tuned to constraints	Core ML or cloud

FAQ: Labeling, augmenting, errors, and object detection in create ML

What's the difference between the create ML app and the create ML framework?

The Create ML app is the drag-and-drop macOS tool bundled with Xcode; the Create ML framework is the Swift API you import into code. Use the app for quick iteration and the framework when you need scripted, repeatable training runs, for example inside a CI pipeline that retrains on new data weekly.

How do you label data for create ML?

Create ML reads labels from folder structure for images, text, and tabular data: one subfolder per class, dropped into the training pane. Object detection needs an explicit JSON annotations file instead of folders, since each image can contain multiple labeled bounding boxes.

How do you augment data in create ML?

The Create ML app applies data augmentation through toggle switches in the training pane: rotation, flip, blur, crop, exposure, and noise. Flip these on when a class has under 100 source images; they generate synthetic variants during training rather than requiring you to supply extra files yourself.

What JSON format does create ML expect?

Object detection training expects an array of objects, each with an "image" filename and an "annotations" array holding "label" and "coordinates" (x, y, width, height) per bounding box. A misnamed key does not throw an error message; it just silently trains on zero annotations, which is worth checking first.

Why am I getting 'no such module create ML' in Xcode?

This happens because the CreateML framework only compiles for macOS targets, not iOS or watchOS. Add a macOS command-line or app target for training code, or guard the import with #if os(macOS) in a shared file. It is a recurring question on Apple Developer Forums and Stack Overflow.

Is there a create ML object detection tutorial?

Apple's WWDC19 "Introducing Create ML" session and the framework's developer documentation both walk through object detection end to end. We trained a bounding-box model from a labeled JSON dataset in under 20 minutes on an M-series Mac while building our own multi-model demo app.

Where do you download create ML?

Create ML ships inside Xcode, no separate download: open Xcode, then Open Developer Tool, then Create ML. The framework becomes available automatically once Xcode's command-line tools are installed, and both require macOS 10.15 or later to run training locally.

Build your first model faster with the right setup

Once your .mlmodel file trains cleanly and Core ML integration runs inside Xcode, the next question is whether to keep iterating solo or bring in engineers who have shipped this pattern before.

Working with Kunster, Netguru built an AR app that uses machine learning and style transfer to transform a user's surroundings into the style of famous painters, letting people experience art in real time through AR portals, record and share videos, and discover museums displaying the original works.

If your team is comparing notes on Reddit threads or Apple Developer Forum pages about training quirks and JavaScript-based demo content, talk to our team about turning that prototype into a shipped feature with consistent support across channels.