Install guide

Install SimWin and run your first Windows build

About ten minutes from download to your app running, most of it waiting for setup’s downloads.

What you need

  • macOS 14 Sonoma or later, on an Apple Silicon or Intel Mac.
  • Flutter, stable channel (3.45 – 3.47), installed and working (flutter doctor).
  • VS Code with the Flutter extension, Android Studio or IntelliJ with the Flutter plugin. Terminal works too.
  • About 3 GB of free disk space, and an internet connection for setup.
You don’t need Windows, Visual Studio or a virtual machine.

Quickest: install from Terminal

One command does everything below: it downloads SimWin from simwin.dev, checks the checksum, Codeaamy’s signature and Apple’s notarization, installs the app, adds the simwin command and runs setup.

curl -fsSL https://simwin.dev/install.sh | bash

Options go after bash -s --, for example curl -fsSL https://simwin.dev/install.sh | bash -s -- --no-setup:

  • --no-setup: install only; set up later in the app or with simwin setup.
  • --no-cli: don’t add the simwin command.
  • --uninstall: remove SimWin completely (see Uninstall).

It never uses sudo. Want to read it first? simwin.dev/install.sh. Prefer clicking? Follow the steps below.

1. Download and install

  1. Download SimWin.dmg and open it.
  2. Drag SimWin onto Applications.
  3. Open SimWin from Applications. It is notarized by Apple, so it opens without warnings.

2. Run setup

The first time SimWin opens, it walks you through setup. Each step checks itself, and you can run it again any time from the Doctor tab.

  1. Check this Mac. macOS version and disk space. On Apple Silicon, SimWin installs Rosetta 2 if it’s missing (macOS asks for an administrator password).
  2. Flutter SDK. SimWin finds your Flutter installation, or you can choose the folder. When you run from your IDE, SimWin always uses the Flutter your IDE runs.
  3. Download components (about 400 MB, each checked against a SHA-256 checksum): the clang-based Windows compiler (llvm-mingw), CMake, Ninja, Wine and DXVK. They are kept in ~/Library/Application Support/SimWin.
  4. Windows environment. SimWin creates the folder your apps run in (about 15 seconds).
  5. Command line tool (optional). Links simwin into /usr/local/bin (administrator password) or ~/.local/bin. Your IDE doesn’t need it.
  6. Add the IDE device. Turns on Flutter’s custom devices (flutter config --enable-custom-devices) and adds “SimWin · Windows 11” to ~/.config/flutter/custom_devices.json. Other custom devices there are left alone.
  7. Self-test. Builds and runs a small sample app, so you know everything works before you try your own. The first build takes about a minute.

3. Run your app

VS Code

  1. Open your Flutter project.
  2. Click the device name in the status bar (bottom right) and choose SimWin · Windows 11.
  3. Press F5 (Run ▸ Start Debugging).

Android Studio and IntelliJ

  1. Open your Flutter project.
  2. Choose SimWin · Windows 11 in the device list in the toolbar.
  3. Click Run or Debug.

Terminal

flutter run -d simwin          # like any other device
simwin open path/to/project    # build and run without an IDE

The first build of a project takes a few minutes: SimWin downloads Flutter’s Windows engine files for your Flutter version (about 100 MB, once per version) and compiles everything. Later builds only recompile what changed. Hot reload (r), hot restart (R), breakpoints and DevTools work as on Windows.

Plugins: If a plugin can’t be built on a Mac (for example one that needs NuGet or WebView2), SimWin leaves it out, tells you which one, and runs the rest of your app.

4. The toolbar and profiles

A toolbar floats above the simulator window:

  • Scale: 100 %, 125 %, 150 % or 200 %, like Windows’ display scaling.
  • Size: common laptop and desktop window sizes.
  • Theme: light or dark, as reported to your app.
  • Locale: including right-to-left Arabic, for testing Directionality.
  • Screenshot and Record: PNG and video of the app window. macOS asks once for Screen Recording permission (System Settings ▸ Privacy & Security ▸ Screen & System Audio Recording).

Save a combination as a profile in the SimWin window, then switch from the toolbar, the menu bar icon or simwin profile use.

Command line reference

CommandWhat it does
simwin open <project>Build and run a project without an IDE
simwin stopStop the running app
simwin screenshot --output shot.pngSave the app window as PNG
simwin profile list | use | create | setManage profiles (scale, size, theme, locale)
simwin statusWhat SimWin is doing right now
simwin doctorCheck everything SimWin needs, with a fix for each problem
simwin reportCreate a problem report to send to us
simwin setup --registerAdd the IDE device again (e.g. after moving the app)
simwin versionSimWin, Wine and toolchain versions

Run simwin help <command> for the options.

Updates

SimWin checks for updates once a day and installs them when you quit. To check now, choose SimWin ▸ Check for Updates….

Uninstall

From Terminal, in one go:

curl -fsSL https://simwin.dev/install.sh | bash -s -- --uninstall

Or by hand:

  1. Remove the IDE device: simwin setup --unregister (or delete the simwin entry from ~/.config/flutter/custom_devices.json).
  2. Quit SimWin and move it from Applications to the Bin.
  3. Delete its folders:
    rm -rf ~/Library/Application\ Support/SimWin ~/Library/Caches/SimWin ~/Library/Logs/SimWin
rm -f /usr/local/bin/simwin ~/.local/bin/simwin

Something not working? See Support and troubleshooting.