Skip to content

How to install and run Briefcase

Briefcase can be installed and run in a few different ways depending on your preferred workflow.

First time?

If this is your first time using Briefcase, you probably want to run through the BeeWare tutorial. This tutorial will walk you through the process of building a complete Python application, including deploying it to multiple platforms.

Default installation

The standard way to install Briefcase is into a Python virtual environment.

  1. Create and activate a virtual environment:
$ python -m venv venv
$ source venv/bin/activate

$ python -m venv venv
$ source venv/bin/activate

C:\...>py -m venv venv
C:\...>venv\Scripts\activate
  1. Install Briefcase using pip:
(venv) $ python -m pip install briefcase

(venv) $ python -m pip install briefcase

(venv) C:\...>py -m pip install briefcase
  1. Run Briefcase commands:
(venv) $ briefcase new
(venv) $ briefcase create
(venv) $ briefcase build
(venv) $ briefcase run

(venv) $ briefcase new
(venv) $ briefcase create
(venv) $ briefcase build
(venv) $ briefcase run

(venv) C:\...>briefcase new
(venv) C:\...>briefcase create
(venv) C:\...>briefcase build
(venv) C:\...>briefcase run

For a full list of commands you can run, see the Command Reference.

Using uvx

If you have uv installed, you can use uvx to download and run Briefcase in a temporary, isolated environment without explicitly installing it first:

$ uvx briefcase new
$ uvx briefcase create
$ uvx briefcase run

Using pipx

If you use pipx to manage CLI applications, you can install Briefcase globally so it is always available on your command line:

pipx install briefcase

You can then run Briefcase from anywhere:

$ briefcase new
$ briefcase create
$ briefcase run

Alternatively, you can use pipx run to execute Briefcase without installing it permanently:

$ pipx run briefcase new
$ pipx run briefcase create
$ pipx run briefcase run