Running the Flutter Widget Previewer from the Command Line

The stable Widget Previewer in Flutter 3.47 is not IDE-only. Learn how to launch it headless from the terminal, how the .widget_preview build cache speeds startup, and where CLI previewing fits in your workflow.

Published on • October 21, 2026

AI Assistant

The Flutter Widget Previewer graduated to stable in Flutter 3.47, and most coverage frames it as an IDE feature — a sidebar tab in Android Studio or VS Code. That undersells it. The previewer is also a standalone tool you can launch from the terminal, which changes where it fits in a team’s workflow: local development without an editor, headless environments, and CI-adjacent checks all become possible.

Source: Flutter Widget Previewer, The Flutter Team, docs.flutter.dev.

The command

From your Flutter project root:

flutter widget-preview start

That single command does two things: it launches a local server, and it opens a real-time preview environment in your browser. There is no separate install step and no IDE dependency — the tool ships with the Flutter SDK. If you have ever wanted to preview a widget on a machine where you are SSH’d into a box or editing with a lightweight editor, this is the entry point.

The `.widget_preview/` cache

The first thing you will notice after a cold start is that subsequent launches are faster. The previewer caches project builds in a .widget_preview/ folder in your project root. This cache is what keeps iteration quick once the initial build is behind you.

Two practical notes:

Add it to .gitignore. It is a build artifact, not source. Committing it wastes space and invites stale-cache confusion across machines.
Delete it when things look wrong. If previews seem stale or a build error lingers after you have fixed the underlying code, clearing .widget_preview/ and restarting is the standard reset.

What you can do in the browser environment

The CLI environment is the same preview surface the IDE tab embeds, so nothing is lost by going headless. Once a widget is annotated with @Preview, the environment gives you per-preview controls:

Zoom in / out / reset — magnify the widget to inspect layout.
Toggle light and dark mode — flip the preview’s theme instantly.
Hot restart a single preview — restart only the specific preview you are editing, without touching the rest.

That per-preview hot restart is the workhorse. When you are iterating on one widget, you are not restarting the whole app — just the slice you are looking at. A separate control at the bottom of the environment hot restarts the entire previewer for the cases where global state (say, a static initializer) has changed underneath you.

Where CLI previewing earns its keep

Because the previewer runs identically in a browser regardless of how it was launched, the CLI mode unlocks a few workflows the IDE tab does not:

Editor-agnostic development. Use Neovim, Emacs, Zed, or a plain terminal and still get live widget previews. The @Preview annotation and the command are all you need.
Remote and containerized work. On a remote dev box or inside a container, the preview server can bind locally while you view it through an SSH tunnel or forwarded port.
Faster onboarding. A new team member can clone, run flutter widget-preview start, and see the component library render — no editor-plugin setup required.

The annotation contract still applies

The CLI does not change what gets previewed. You still mark targets with @Preview from package:flutter/widget_previews.dart, applied to top-level functions, static methods, or public widget constructors that take no required arguments:

import 'package:flutter/widget_previews.dart';

@Preview(name: 'My Sample Text')
Widget mySampleText() => const Text('Hello, World!');

The command launches the environment; the annotations decide what appears in it.

Key takeaways

The Widget Previewer is a first-class CLI tool, not just an IDE convenience. flutter widget-preview start spins up a local server and a browser-based preview environment with full zoom, theme-toggle, and per-preview hot-restart controls. The .widget_preview/ build cache makes repeat launches fast — gitignore it, and clear it when previews look stale. Going headless opens up editor-agnostic, remote, and containerized workflows that the sidebar tab never could.