Getting Started

In this guide we will walk you through setting up your Briefcase environment for development and testing. We will assume that you have a working Python 3 install. If you don’t have Python 3 set up yet, this guide will help you get started.


Briefcase (and the whole BeeWare toolchain) requires Python 3. Support for different Python 3 minor versions varies depending on the platform you’re targeting; Python 3.5+ will give you the best results.

Create a Virtual Environment

We recommend creating a virtual environment for your project. A virtual environment is a self-contained packaging of Python where you can install the libraries needed for this project without worrying about conflicting with your other projects.

Run these commands to create the directory for your project and set up the virtual environment:

$ mkdir tutorial
$ cd tutorial
$ python3 -m venv venv
$ . venv/bin/activate    # For Windows CMD: venv\Scripts\activate

The last command activates the virtual environment, which means that any libraries you install at this point will go into this environment. See the Python venv documentation for complete documentation of virtual environments.


On some versions the activate script may be in the venv/Scripts/ folder in which case swap: $ . venv/bin/activate for $ . venv/Scripts/activate

Install Briefcase

The next step is to install Briefcase:

$ pip install briefcase

Install Toga

Next, install Toga into your virtual environment:

macOS or Linux

(venv) $ pip install --pre toga


(venv) C:\...>pip install --pre toga

(note: a pre-release version of Toga is currently in use.)

Install platform dependencies

Next, you’ll need to make sure you’ve got the platform-specific dependencies for the platforms you’re going to target.


If you’re using Windows 10, you may need to enable the .NET 3.5 framework on your machine. Select “Programs and Features” from the Start menu, then “Turn Windows features on or off”, and ensure “.NET Framework 3.5 (Includes .NET 2.0 and 3.0)” is enabled.


There are no additional dependencies required to support OSX.


You’ll need install GTK+ 3.10 or later. This is the version that ships starting with Ubuntu 14.04 and Fedora 20. You also need to install the Python 3 bindings to GTK+. If you want to use the WebView widget, you’ll also need to have WebKit, plus the GI bindings to WebKit installed. This means you’ll need to install the following:

  • Ubuntu 14.04 apt-get install python3-gi gir1.2-webkit2-3.0
  • Ubuntu 16.04 apt-get install python3-gi gir1.2-webkit2-4.0 or apt-get install python3-gi gir1.2-webkit2-3.0
  • Fedora 20+ dnf install python3-gobject pywebkitgtk or yum install python3-gobject pywebkitgtk
  • Debian Stretch apt-get install python3-gi gir1.2-webkit2-4.0


  • Install XCode from the App store. Once you’ve installed XCode, you must also install the Xcode Command Line Tools. This can be done from the Preference panel within XCode itself.


  • Install Android Studio. When you start Android Studio for the first time, you’ll be provided a wizard to configure your installation; select a “standard” installation.

  • Put the sdk/tools, sdk/platform-tools and sdk/tools/bin directories in your path.

    • On macOS: ~/Library/Android/sdk/tools, ~/Library/Android/sdk/platform-tools and ~/Library/Android/sdk/tools/bin
  • Set the ANDROID_SDK_HOME directory

    • On macOS: ~/Library/Android/sdk
  • Update the SDKs:

    $ sdkmanager --update
  • Create a virtual device image, following these instructions.

  • Install Gradle.

  • Start the emulator:

    $ emulator @Nexus_5X_API_22


If you are going to create a web app with Django, you need:

  • Install an LTS version of Node (6.9.x)
  • Install NPM 4.x or higher

Next Steps

You now have a working Briefcase environment, so you can start the first tutorial.