Starts the application, using the packaged version of the application code. By default, targets the current platform’s default output format.

If the output format is an executable (e.g., a macOS .app file), the run command will start that executable. If the output is an installer, run will attempt to replicate as much as possible of the runtime environment that would be installed, but will not actually install the app. For example, on Windows, run will use the interpreter that will be included in the installer, and the versions of code and dependencies that will be installed, but won’t run the installer to produce Start Menu items, registry records, etc.

Test mode

The run command can also be used to execute your app’s test suite, in the packaged environment (e.g., on the iOS simulator, or from within a Linux Flatpak). When running in test mode (using the --test option), a different entry point will be used for the app: if your app is contained in a Python module named myapp, test mode will attempt to launch tests.myapp. Your app is responsible for providing the logic to discover and start the test suite.

The code for your test suite can specified using the test_sources setting; test-specific requirements can be specified with test_requires. Test sources and requirements will only be included in your app when running in test mode.

Briefcase will monitor the log output of the test suite, looking for the output corresponding to test suite completion. Briefcase has built-in support for pytest and unittest test suites; support for other test frameworks can be added using the test_success_regex and test_failure_regex settings.


To run your application on the current platform’s default output format:

$ briefcase run

To run your application for a different platform:

$ briefcase run <platform>

To run your application using a specific output format:

$ briefcase run <platform> <output format>


The following options can be provided at the command line.

-a <app name> / --app <app name

Run a specific application target in your project. This argument is only required if your project contains more than one application target. The app name specified should be the machine-readable package name for the app.

-u / --update

Update the application’s source code before running. Equivalent to running:

$ briefcase update
$ briefcase run


Run the test suite in the bundled app environment. Running run --test forces an update and rebuild, to ensure that the packaged application contains all the test dependencies and code. To prevent this update and build, use --no-update.


Prevent the automated update that is performed when specifying by the --test option. This option should only be required if you need to build your app on one machine, and run it on another.