yolo-ios-app

English | 简体中文

🚀 Ultralytics YOLO for iOS: App and Swift Package

Ultralytics YOLO for iOS provides on-device real-time inference for object detection, instance segmentation, semantic segmentation, depth estimation, classification, pose estimation, and oriented bounding box detection. The SDK supports both YOLO11 (with Core ML NMS) and YOLO26 models (shipped with nms=False for NMS-free inference). Download the app from the App Store, or integrate the Swift package into your own applications.

  

✨ Features

• Swift and Core ML throughout, running on the Apple Neural Engine and GPU
• Opt-in Apple Core AI (.aimodel) models on iOS 27 and later devices; Core ML (.mlpackage) remains the default
• Camera-rate (~30 FPS) real-time inference on recent iPhones — see docs/performance.md for on-device profiling
• Native UI following Apple interface guidelines
• YOLO26 and YOLO11 models supported, including NMS-free and raw outputs
• No third-party dependencies — pure Swift on Apple’s first-party frameworks

📂 Repository Content

This repository contains two components for running YOLO models on Apple platforms (Edge AI):

Ultralytics YOLO iOS App (Main App)

The primary iOS application allows easy real-time YOLO inference using your device’s camera or image library. The shipped app bundles all seven official nano Core ML models, larger variants download on demand, and you can also test your custom Core ML or opt-in Core AI (.aimodel, iOS 27+ devices) models by adding them to the app project.

Swift Package (YOLO Library)

A lightweight Swift package designed for iOS and iPadOS. It handles model loading, inference, and postprocessing for YOLO models like YOLO26 in your own applications, with a few lines of SwiftUI:

// Perform inference on a UIImage
let result = model(uiImage)

// Use the built-in camera view for real-time inference with a model bundled in your app
var body: some View {
    YOLOCamera(
        modelPathOrName: "yolo26n-seg",
        task: .segment,
        cameraPosition: .back
    )
    .ignoresSafeArea()
}

📦 Official Model Assets

Official models are GitHub release assets, not large files committed to the repositories. The main iOS app downloads the seven nano Core ML assets at build time and bundles them into the app; larger app models, the Swift package’s YOLO(url:) loading, and Flutter package assets download official models on first use and cache them locally.

The main YOLOiOSApp bundles all seven nano models (one per task: detect, segment, semantic, depth, classify, pose, OBB) into the shipped app, including App Store/archive builds. They are downloaded at build time from the GitHub release assets by a Download YOLO Models Xcode build phase that runs scripts/download-models.sh — the .mlpackage files are never committed to the repo (*.mlpackage is gitignored). The step is idempotent and is skipped on GitHub Actions CI, which runs the same script in its own step.

URL patterns:

• Core ML: https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/<model>.mlpackage.zip
• Core AI (opt-in): https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/<model>.aimodel.zip
• LiteRT: https://github.com/ultralytics/yolo-flutter-app/releases/download/v0.6.6/<model>_w8a32.tflite

Core ML (.mlpackage) remains the default. Core AI (.aimodel) is an opt-in for iOS 27 and later devices: pass an .aimodel path or an .aimodel.zip URL. It is not available on earlier iOS versions or in the iOS Simulator. See docs/performance.md for the measured trade-offs. In the iOS app, turn on Settings → Ultralytics YOLO → Core AI Models (iOS 27+) (off by default) and return to the app: it then lists, downloads and loads the Core AI assets instead of the Core ML ones.

let local = YOLO("/path/to/yolo26n.aimodel", task: .detect)
let remote = YOLO(url: URL(string: "https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/yolo26n.aimodel.zip")!, task: .detect)

The iOS app registry is RemoteModels.swift. It enumerates YOLO26 n/s/m/l/x assets for detect, segment, semantic, depth, classify, pose, and OBB and points each model ID at the v8.3.0 release. The Core ML and Core AI columns below are owned by this repo; the LiteRT column summarizes the Flutter repo’s Android export script and release assets.

Export scripts require ultralytics>=8.4.142, and >=8.4.155 for Core AI. Core ML assets use nms=False to select the NMS-free head for detect, segment, pose, and OBB. Core AI assets keep the package default raw head (nms=None), which the SDK decodes with its existing Swift NMS: on an iPhone 17 Pro it is about twice as fast in inference as both the Core AI end-to-end head and the Core ML assets (docs/performance.md). Core AI has no NMS operator, so there is no NMS pipeline stage as in Core ML, and the Ultralytics package has no int8 Core AI export, so Core AI assets are FP16 and roughly twice the download size of the int8 Core ML assets. Both formats carry the same Ultralytics metadata keys and values (task, names, imgsz, stride, end2end, …), and the SDK decodes either head by output shape. With useGpu true (hardware acceleration) Core AI places the model across the Neural Engine, GPU and CPU; useGpu false pins it to the CPU. Classification, semantic, and depth retain their native outputs. LiteRT uses nms=None for raw one-to-many outputs with Android-side NMS. nms=True embeds NMS where supported. The end2end metadata field describes the exported graph; use nms to configure exports.

Core ML and Core AI Release Workflow

The published v8.3.0 binary dimensions are recorded above. The export script scripts/export-models.py defines the official exports, int8 Core ML and FP16 Core AI settings, .mlpackage.zip and .aimodel.zip packaging, the optional local app-copy step, and optional GitHub release upload. It exports Core ML by default; add --formats coreai (or --formats coreml coreai) for the opt-in Core AI assets, which needs macOS 26 or later on Apple silicon, ultralytics>=8.4.155 and coreai-torch>=0.4.2. If its export matrix changes, replace the generated assets in v8.3.0 and update this table together.

uv venv --python 3.13 .venv
uv pip install "ultralytics[export-coreml]>=8.4.142"
uv run python scripts/export-models.py

Useful variants:

# Export only nano task models for local validation and copy them into YOLOiOSApp/Models/.
uv run python scripts/export-models.py --sizes n --copy-to-app

# Export and replace all official Core ML assets in the existing release.
uv run python scripts/export-models.py --upload --repo ultralytics/yolo-ios-app --tag v8.3.0

# Export and replace the opt-in Core AI assets (macOS 26 or later on Apple silicon).
uv run python scripts/export-models.py --formats coreai --upload --repo ultralytics/yolo-ios-app --tag v8.3.0

The script exports from checkpoints named yolo26<size><suffix>.pt, for example yolo26n.pt, yolo26s-seg.pt, yolo26m-sem.pt, yolo26l-pose.pt, and yolo26x-obb.pt. Official Core ML assets use nms=False to select NMS-free detect, segment, pose, and OBB outputs, while Core AI assets keep the raw head and the SDK applies its Swift NMS; depth retains its raw dense output. Swift-side postprocessing handles these task outputs (classify and semantic outputs need no NMS decode).

Android LiteRT Counterparts

The Android assets used by the Flutter package are maintained in the Flutter repo, not this iOS repo. Their canonical export script is scripts/export-tflite-models.py in ultralytics/yolo-flutter-app; it exports the matching YOLO26 task/size matrix as w8a32 .tflite assets. This dynamic-range format uses int8 weights and FP32 activations, needs no calibration data, and is published in yolo-flutter-app v0.6.6.

🛠️ Quickstart Guide

New to YOLO on mobile or want to quickly test your custom model? Start with the main YOLOiOSApp. The seven nano task models are bundled at build time, so the app can run offline after installation; larger model sizes download on demand.

• Ultralytics YOLO iOS App (Main App): The easiest way to experience YOLO inference on iOS.

Ready to integrate YOLO into your own project? Explore the Swift Package and example applications.

• Swift Package (YOLO Library): Integrate YOLO capabilities into your Swift app.
• Example Apps: See practical implementations using the YOLO Swift Package.

Add the UltralyticsYOLO package to your app with Swift Package Manager:

.package(url: "https://github.com/ultralytics/yolo-ios-app.git", from: "8.9.22")

Or with CocoaPods:

pod 'UltralyticsYOLO', '~> 8.9'

Then import UltralyticsYOLO and use the YOLO class — see the Swift Package README for full usage. The same UltralyticsYOLO package powers both this native iOS app and the Ultralytics YOLO Flutter plugin, keeping one source of truth across platforms.

Import a custom model from Ultralytics Platform

In Platform, click the QR button on a completed Core ML or Core AI export, then open Ultralytics YOLO, tap the QR button in the bottom toolbar, and point the existing camera preview at the code. While scanning, the camera dims around a viewfinder; tap Cancel or the QR button again to return to inference. Confirm the model name, task, and download size. The app installs the model and adds it to the Custom section of the model picker. The header shows the task, with Custom added for imported models, above the active model name. Tap it to choose a custom import or any official model in one compact list, with size choices grouped into one row per task. The Custom section also provides Scan QR and a help button for the Platform export guide. Tap the trash icon next to a custom model to remove it. The last selected custom model is restored on launch and works offline.

Exports must use batch 1 and static inputs. Core AI requires a supported iOS 27+ device; use Core ML for broader compatibility. Importing a model uses its actual format independently of the official-model Core AI setting. Links authorize one export for 24 hours; anyone with the link can download during that window. Installed models continue working after expiry, and separate exports never overwrite each other even when their names match.

🧪 Testing Procedures

This repository includes comprehensive unit tests for both the YOLO Swift Package and the example applications, ensuring code reliability and stability.

Running Tests

Tests require Core ML model files (.mlpackage), which are not committed to the repository due to their size. To run the package tests with model validation, first run the same downloader used by CI and the app build phase:

bash scripts/download-models.sh

This downloads the seven nano Core ML packages into Tests/YOLOTests/Resources/ and copies them into YOLOiOSApp/Models/<Task>/ for the main app bundle. Tests run on the iOS Simulator, which does not ship Core AI, so they exercise the Core ML backend; the opt-in Core AI backend is validated on an iOS 27 device (docs/performance.md). You can also export or replace these packages with custom Core ML models using the Ultralytics Python library’s export function. If a specific test target supports SKIP_MODEL_TESTS, keeping it set to true skips tests that require loading and running a model.

Test Coverage

• YOLO Swift Package: Includes tests for core functionalities like model loading, preprocessing, inference, and postprocessing across different tasks.
• Example Apps: Contains tests verifying UI components, model integration, and real-time inference performance within the sample applications.

Test Documentation

Each test directory (e.g., Tests/YOLOTests) may include a README.md with specific instructions for testing that component, covering:

• Required model files and where to obtain them.
• Steps for model conversion and setup.
• Overview of the testing strategy.
• Explanation of key test cases.

💡 Contribute

We warmly welcome contributions to our open-source projects! Your support helps us push the boundaries of Artificial Intelligence (AI). Get involved by reviewing our Contributing Guide and sharing your feedback through our Survey. Thank you 🙏 to all our contributors!

📄 License

Ultralytics provides two licensing options to accommodate diverse use cases:

• AGPL-3.0 License: An OSI-approved open-source license ideal for academic research, personal projects, and experimentation. It promotes open collaboration and knowledge sharing. See the LICENSE file for the full license text.
• Enterprise License: Tailored for commercial applications, this license allows the integration of Ultralytics software and AI models into commercial products and services without the open-source requirements of AGPL-3.0. If your scenario involves commercial use, please contact us via Ultralytics Licensing.

📮 Contact

• For bug reports and feature requests related to this iOS project, please use GitHub Issues.
• For questions, discussions, and support regarding Ultralytics technologies, join our active Discord community!