Standalone Application with Briefcase — Click Documentation (8.3.x)

# Standalone Application with Briefcase

Briefcase is a tool for packaging Python projects as standalone native applications. It can produce installers and executables for macOS, Windows, and Linux that do not require the user to install Python or any dependencies.

- Produces platform-native installers (`.pkg` on macOS, `.msi` on Windows, `.deb`/`.rpm` on Linux).

- Bundles a Python interpreter and all dependencies.

- Supports passing command line arguments to the app.

This page outlines the basics of packaging a Click application with Briefcase. Be sure to read its documentation and use `briefcase --help` to understand what features are available.

## Installation

Install Briefcase in the virtual environment:

    pip install briefcase

## Configuration

Add a `[tool.briefcase]` section and a `[tool.briefcase.app.<app-name>]` section to `pyproject.toml`. Set `console_app = true` so Briefcase treats the project as a command line application rather than a GUI application.

Given a Click application with the following project structure:

    hello-cli/
        src/
            hello_cli/
                __init__.py
                app.py
        LICENSE
        pyproject.toml

Where `app.py` contains a Click command:

    import click

    @click.command()
    @click.argument("name", default="World")
    @click.option("--count", default=1, help="Number of times to greet.")
    def main(name, count):
        """Greet someone by NAME (default: World)."""
        for _ in range(count):
            click.echo(f"Hello, {name}!")

Add the following Briefcase configuration to `pyproject.toml`:

    [tool.briefcase]
    project_name = "Hello CLI"
    bundle = "com.example"
    version = "0.0.1"
    url = "https://example.com/hello-cli"
    license.file = "LICENSE"
    author = "Your Name"
    author_email = "you@example.com"

    [tool.briefcase.app.hello-cli]
    formal_name = "Hello CLI"
    description = "My first application"
    long_description = """More details about the app should go here.
    """
    sources = [
        "src/hello_cli",
    ]
    console_app = true
    requires = [
        "click",
    ]

The key settings are:

- `console_app = true` – tells Briefcase this is a terminal application, not a GUI.

- `sources` – the list of source packages to include.

- `requires` – the Python dependencies to bundle (Click and any other libraries the project needs).

## Entry Point

Briefcase launches the application by running the package with `python -m <package>`, so a `__main__.py` file must exist in the package. Without it, Briefcase will not be able to start the application.

Create `__main__.py` in the package directory and call the Click command:

    from hello_cli.app import main

    if __name__ == "__main__":
        main()

## Running

Use `briefcase dev` to run the application directly from the source tree. Pass command line arguments after `--`:

    $ briefcase dev -- World
    Hello, World!
    $ briefcase dev -- World --count 2
    Hello, World!
    Hello, World!

## Building and Packaging

To create a distributable executable, run the following commands:

    briefcase create
    briefcase build
    briefcase package

`briefcase create` downloads a Python interpreter and installs dependencies into an isolated app bundle. `briefcase build` compiles the app, and `briefcase package` produces the final platform installer.

On macOS, this produces a `.pkg` installer. On Windows, it produces a `.msi` installer. On Linux, it produces a system package (`.deb`, `.rpm`, etc.) for the current distribution.

Once installed, users can run the application directly from the terminal:

    $ hello-cli World
    Hello, World!
    $ hello-cli World --count 2
    Hello, World!
    Hello, World!