flutter-tvos

A Flutter toolchain for building and running Flutter apps on Apple TV (tvOS).

flutter-tvos is a drop-in CLI companion to the Flutter SDK — same commands, same hot reload, same DevTools — targeting tvOS instead of iOS.

macOS only. Xcode is required.

Current version

• flutter-tvos: 1.6.0
• Flutter SDK: 3.47.0 (4cf24164269a5ebf0c16a028a00727d0e77bbb05)
• tvOS engine artifacts: engine-495915c579071a4ef6a5014637166d5231cb4aac (origin-signed)

The engine artifact tag is the commit that produced those artifacts, rather than a Flutter version. A version-shaped tag went stale as soon as one patch set was reused across Flutter releases; a SHA names what was actually built.

Installation

git clone https://github.com/fluttertv/flutter-tvos.git
cd flutter-tvos
export PATH="$PATH:$PWD/bin"
flutter-tvos precache
flutter-tvos doctor

See Getting started for the full setup guide.

Usage

flutter-tvos substitutes the original flutter CLI command.

# Check the installed tooling and list all connected devices.
flutter-tvos doctor -v
flutter-tvos devices

# Create a new app project.
flutter-tvos create my_tv_app
cd my_tv_app

# Build and run on a tvOS Simulator.
flutter-tvos run -d <simulator_id>

# Build and run on a physical Apple TV in release mode.
flutter-tvos run -d <device_id> --release

• See Supported commands for all available commands and usage examples.
• See Getting started to create your first app and try hot reload.
• To update flutter-tvos to the latest released version, run flutter-tvos upgrade (use flutter-tvos upgrade --verify-only to just check).
• To use a different Flutter version, run flutter-tvos versions to see what is supported and flutter-tvos use <version> to switch. Each version is its own release line, pinning the Flutter SDK and the matching tvOS engine together.

Platform identity & limitations

flutter-tvos treats tvOS as its own platform at both the build and runtime layers. Read this section before adding dependencies to an existing iOS codebase — the separation has real consequences for plugins and cross-platform apps.

Runtime identity

On a tvOS build, the Dart VM reports:

API	Value on tvOS	Value on iOS
Platform.operatingSystem	"tvos"	"ios"
Platform.isIOS	true	true
Platform.isTvOS	true	false
defaultTargetPlatform	TargetPlatform.iOS	TargetPlatform.iOS

Platform.isIOS is true on tvOS. Apple TV runs the same Darwin kernel, UIKit, Metal, and Foundation as iPhone and iPad — it's part of the iOS family. Standard Flutter widgets that branch on Platform.isIOS or defaultTargetPlatform already render correctly on Apple TV: Cupertino styling, SF font, and iOS-style page transitions all work out of the box, with no Flutter framework changes required.

The Flutter framework that flutter-tvos uses is unmodified. tvOS identity is contributed entirely by the Dart VM in our engine build and by the flutter-tvos CLI itself.

Plugin platform key

A Flutter plugin advertises which platforms it supports under flutter.plugin.platforms in its pubspec.yaml. Plugins target tvOS by adding a tvos: entry there:

flutter:
  plugin:
    platforms:
      tvos:
        pluginClass: MyPlugin

A tvOS build only loads plugins that declare this key. Plugins targeting only ios: are not picked up — Apple TV needs different native code in many cases (no WebKit, no haptics, no clipboard, no camera, focus-engine input instead of touch), so the safe default is to require explicit opt-in.

In practice each plugin with native code ships an extra federated package (e.g. url_launcher → url_launcher_tvos) that adds the tvOS implementation. The same model is used by flutter-tizen, and flutter-elinux.

A FlutterTV-curated index of ported plugins is at github.com/fluttertv/plugins (also on pub.dev under the fluttertv.dev publisher). If a plugin you need isn't there, flutter-tvos plugin port scaffolds a federated *_tvos package from any iOS or macOS plugin — see Porting an existing plugin.

Dependency management. Newly created tvOS apps use Swift Package Manager by default: the build generates a FlutterGeneratedPluginSwiftPackage that vends the engine plus every plugin shipping a tvos/Package.swift, and wires it into the Xcode project. CocoaPods still works — a plugin that ships only a podspec is resolved through the Podfile, and the two coexist (a plugin with a Package.swift is owned by SPM and skipped by CocoaPods). Plugins produced by flutter-tvos plugin port ship both, so they work either way.

Writing cross-platform apps (iOS + Android + tvOS)

If your app already targets iOS/Android and you're adding tvOS support, keep these patterns in mind:

1. Don't rely on Platform.isIOS alone for "phone/tablet iOS" logic. It's also true on Apple TV. Refine with Platform.isTvOS:

// ❌ Will run on Apple TV too
if (Platform.isIOS) {
  showTouchGestureHint();
}

// ✅ Only iPhone / iPad
if (Platform.isIOS && !Platform.isTvOS) {
  showTouchGestureHint();
}

2. Exclude tvOS from iOS-only code paths when iOS-specific behavior makes no sense on a TV (touch gestures, haptics, status-bar tweaks, keyboard dismissal, clipboard, web views, camera, etc.):

import 'package:flutter_tvos/flutter_tvos.dart';

if (FlutterTvosPlatform.isIos) {                  // iPhone / iPad only (NOT tvOS)
  // Use iPhone-specific plugin
}

if (FlutterTvosPlatform.isTvos) {                 // Apple TV only
  // 10-foot UI, focus-based navigation, D-pad
}

if (FlutterTvosPlatform.isAppleMobile) {          // iPhone, iPad, OR Apple TV
  // Any iOS-family OS (UIKit + Foundation present)
}

3. Build focus-first on tvOS. Apple TV has no touch — users navigate with the Siri Remote via the system focus engine. Apply Focus / FocusableActionDetector widgets and design for D-pad traversal.

4. Plugin dependencies: if your iOS app uses url_launcher, shared_preferences, path_provider, etc., each one needs a tvOS federated package (url_launcher_tvos, shared_preferences_tvos, …) or your tvOS build will compile but calls will throw MissingPluginException at runtime. Before porting, audit your pubspec.yaml for plugins with native iOS code and check whether a _tvos variant exists.

5. ios/ and tvos/ directories are independent. Running flutter-tvos create scaffolds a separate tvos/ project sibling to ios/. They have their own Podfile, their own Info.plist, their own AppDelegate. Do not symlink or share them — the build settings diverge (tvOS SDK, UIKit-without-WebKit, no haptics/clipboard/status bar, etc.).

6. Conditional imports in pure-Dart packages — use dart.library.io guards if you publish a package that should behave differently on tvOS:

import 'package:my_package/io_stub.dart'
    if (dart.library.io) 'package:my_package/io_impl.dart';

Then inside io_impl.dart, branch on Platform.isTvOS vs Platform.isIOS.

Known limitations

• No touch gestures. All input is Siri Remote (focus-based) or MFi game controller. Touch-only widgets (GestureDetector, Dismissible, swipe-to-reveal) don't fire on Apple TV. Build with Focus / FocusableActionDetector / Shortcuts instead.
• Text input goes through the tvOS virtual keyboard. TextField works on Apple TV: focusing it brings up the full-screen system keyboard view controller. Hardware keyboards paired over Bluetooth also work. TextField.autofocus is supported but participates in the focus engine — it competes with other focusables and isn't always the first focus on screen.
• No WebKit / webview_flutter. tvOS does not ship WebKit. Plugins depending on WKWebView will not compile for Apple TV.
• No haptics, clipboard, or status bar. HapticFeedback.*, Clipboard.*, and SystemChrome.setSystemUIOverlayStyle are no-ops on tvOS.
• No fork(). Apple TV disallows fork() entirely. Some background-work libraries are affected; Perfetto's daemonize path is already patched in our engine build.
• On-device debug needs a debugger attached. Debug (JIT) now works on a physical Apple TV — flutter-tvos run -d <appletv> --debug gives you hot reload, hot restart, and DevTools over the wireless CoreDevice tunnel (the bundled tvOS debug engine artifact ships the NOTIFY_DEBUGGER_ABOUT_RX_PAGES hook lldb's attach needs). Because Apple TV is wireless-only the attach is slower than USB iOS; the simulator remains the fast-iteration path for debug. Release/profile on device run AOT and need no debugger.
• Metal-only rendering. No OpenGL backend. Apps relying on GL-specific platform views will not work.

Add tvOS support to an existing plugin

If a plugin already implements iOS or macOS, flutter-tvos plugin port scaffolds a federated <plugin>_tvos sibling package from it — the source plugin is never modified.

flutter-tvos plugin port --from-pub url_launcher_ios --output url_launcher_tvos

See Porting an existing plugin for the full flag reference, what the transformer does and doesn't do, and how to read the generated PORTING_REPORT.md. The fluttertv/plugins repo is 11 packages produced this way — useful as worked examples.

Docs

App development

• Getting started
• Supported commands
• Debugging apps
• Publishing to the App Store

Plugin development

• Writing a tvOS plugin
• Porting an existing plugin

Project internals

• Architecture

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for details.

# Run tests
flutter/bin/dart test test/

License

BSD 3-Clause — see LICENSE.

This project incorporates code from Flutter and flutter-tizen (both BSD 3-Clause).
See THIRD_PARTY_LICENSES.md for full attribution.

---

flutter-tvos is an independent community project and is not affiliated with, endorsed by, or sponsored by Google LLC or Apple Inc. Flutter is a trademark of Google LLC. Apple TV and tvOS are trademarks of Apple Inc.