Set Up a BeeWare Project

You have a great Python app idea, but the moment you think about shipping it to a phone, your momentum dies. Do you learn Swift or Kotlin? Maintain two codebases? When you just want to focus on your business logic, the cross-platform framework maze feels overwhelming. This lesson cuts through that pain and shows you exactly how to set up a BeeWare project with Briefcase — giving you a single Python codebase that you can package for Android, iOS, macOS, Windows, and Linux, starting today.

The problem this lesson solves

Every mobile developer has hit this wall: you write a Python prototype, it works beautifully on your laptop, and then you hit the deployment wall. Native toolchains want their own language, their own project structure, and their own build systems. If you have ever tried to manually wire up an Android project with Python bindings, you know the configuration sprawl — dozens of XML files, build scripts, and platform-specific secrets. It’s a productivity killer.

The real problem is not the app itself; it’s the project scaffolding. Without a tool that handles cross-platform packaging, you lose days to setup. Briefcase solves exactly this. It acts as a single entry point: it creates the initial project skeleton for a BeeWare app, manages virtual environments, builds your app for the platform you target, and even runs it — all with commands that feel familiar to Python developers. After this lesson, you will be able to scaffold a new project, verify it runs, and know the exact steps to package it, without ever touching platform-specific build files manually.

Core concept / mental model

Think of Briefcase as a project concierge for your Python app. In a traditional workflow, you call platform-specific tools directly: gradlew for Android, xcodebuild for iOS, and so on. With Briefcase, you talk to one tool, and it delegates to the right underlying machinery. Your project is organized around a single pyproject.toml file — the same file you already use for packaging your Python libraries. That file contains all the metadata: app name, bundle identifier, dependencies, and platform-specific build settings.

Visually, imagine a layer cake:

1. Top layer: Your Python code, pure and platform-agnostic. This is where your logic lives.
2. Middle layer: Briefcase, the automation layer that reads your pyproject.toml and decides what to do.
3. Bottom layer: Platform toolchains (Android SDK, Xcode, etc.) that Briefcase invokes on your behalf.

You stay in the top layer and give commands to the middle layer — Briefcase does the heavy lifting. The key term to remember is template: Briefcase uses platform-specific templates to generate a native project structure (like an Android Studio project) that wraps your Python code. You never edit those generated files directly; you edit your Python code and rerun Briefcase.

This mental model is powerful because it means you can build your app once and ship it anywhere, with the same dependency management and the same test runners. When you hear “one codebase, many platforms,” this is the mechanism behind it.

How it works step by step

The process of setting up a BeeWare project with Briefcase is a predictable sequence of five phases. Here is the logical breakdown — cause and effect for each step.

1. Install Briefcase

Briefcase is a Python package, so it installs with pip. This step ensures the briefcase command is on your PATH. Without it, nothing else works.

2. Initialize the project

The briefcase new command prompts you for essential info: your app’s formal name, the package name (a unique reverse-domain identifier), and the project name. It then creates a folder structure that includes:

• pyproject.toml — your app’s DNA.
• src/<project_name>/ — where your Python source lives.
• tests/ — a basic test suite.
• resources/ — app icons and splash screens.

Why this order? The new command must run before you can build or run, because it creates the config that all later commands consume.

3. Run your app in development mode

The briefcase dev command starts the app on your local machine. It sets up a virtual environment, installs dependencies, and launches your app. This is your fast feedback loop. You would run this many times while developing.

4. Create a platform build

When you are ready, run briefcase create followed by briefcase build with a platform target (like android or macOS). Briefcase generates the native project template, then compiles your Python code into an installable artifact. This is where the magic of packaging happens.

5. Run on a device or simulator

Finally, briefcase run deploys the built app to a connected device or an emulator. When the build is ready, this is the step that makes it visible to the world.

Each command builds on the previous one, so if you skip create, build will fail. Think of it as a pipeline: new → dev → create → build → run.

Hands-on walkthrough

Let’s do this for real. I will assume you have Python 3.8+ and pip available. Open a terminal and follow along.

Step 1: Install Briefcase

python -m pip install briefcase

Verify the installation:

briefcase --version

You should see output like briefcase v0.3.18. If you get a command not found error, your Python scripts folder is not on your PATH — check the troubleshooting section.

Step 2: Initialise a new project

Run briefcase new and answer the prompts. Here is an example session:

$ briefcase new
** Project Name **
The name of your project to use for the distribution (e.g. 'PyBee'): [My Project] > HelloWorld
** Bundle Identifier **
The bundle identifier for your application (e.g. 'com.example'): [com.example] > com.example
** Project Name **
The Python project name (e.g. 'helloworld'): [HelloWorld] > helloworld

After answering, Briefcase creates the directory structure. A typical project looks like this:

helloworld/
├── pyproject.toml
├── LICENSE
├── README.rst
├── src/
│   └── helloworld/
│       ├── __init__.py
│       └── app.py
└── tests/
    ├── __init__.py
    └── test_app.py

Step 3: Run your app in dev mode

cd helloworld
briefcase dev

You should see a window open with the text Hello, World!. If you are on a headless machine, this may fail — jump to troubleshooting.

Step 4: Build for Android (as an example)

Ensure you have the Android SDK installed, then run:

briefcase create android
briefcase build android

This will take a while the first time because it downloads Gradle and dependencies. When it finishes, you will have an APK.

Step 5: Run on an Android emulator

briefcase run android

If you have an emulator running, the app will launch on it.

Expected output: On a device or emulator, you will see the same “Hello, World!” window — proving that the same code runs on both desktop and mobile.

Compare options / when to choose what

BeeWare is not the only Python mobile framework. It is essential to know when to reach for it versus alternatives. Here is a clean comparison:

When to choose BeeWare: If you want true native widgets and you want to stay in Python. It is ideal for productivity tools, simple business apps, and when you want to reuse your existing Python backend logic.

When to choose something else: If you need heavy animations, opt for Flutter; if your team is already JavaScript-heavy, React Native. Kivy is better for canvas-heavy UIs that don’t need native widgets.

Troubleshooting & edge cases

Even with a smooth tool, you will hit bumps. Here are the most common failures and how to fix them.

Error: briefcase: command not found

Your Python scripts folder is not in PATH. Find it with python -m site --user-base and add the bin folder to your shell profile. For example, on Linux:

export PATH="$HOME/.local/bin:$PATH"

Error: App window does not appear on briefcase dev

You are on a headless Linux environment. BeeWare requires a display server. Install xvfb and run with xvfb-run briefcase dev, or work on a machine with a GUI.

Error: Android build fails with “SDK location not found”

Briefcase looks for the Android SDK in specific locations. Set the ANDROID_HOME environment variable:

export ANDROID_HOME="$HOME/Android/Sdk"

Then retry briefcase create android. Also ensure you have accepted the SDK licenses: run sdkmanager --licenses.

Error: Cannot find package 'toga' on import

Your virtual environment is stale. Run briefcase dev from the project root — it recreates the environment as needed. If you manually added a dependency, update pyproject.toml in the dependencies section and rerun briefcase dev.

What you learned & what's next

You have now mastered the core of setting up a BeeWare project with Briefcase. You understand the problem of cross-platform scaffolding, the mental model of Briefcase as a delegating tool, the step-by-step pipeline of new → dev → create → build → run, and you have hands-on experience scaffolding and running a project. You also know how to compare BeeWare to Kivy and Flutter, and you can troubleshoot the most common setup errors.

You achieved both learning objectives: you can explain how Briefcase wraps native toolchains, and you can complete a practical setup exercise. Next in the track, you will dive into building your first BeeWare app with Toga — learning how to structure UI code, handle events, and prepare your app for real device deployment. Congratulations, you are no longer stuck at the setup wall; you are officially a BeeWare developer.