The app is the main entry point and container for the Toga GUI.


The app class is used by instantiating with a name, namespace and callback to a startup delegate which takes 1 argument of the app instance.

To start a UI loop, call app.main_loop()

import toga

def build(app):
    # build UI

if __name__ == '__main__':
    app = toga.App('First App', 'org.pybee.helloworld', startup=build)

Alternatively, you can subclass App and implement the startup method

import toga

class MyApp(toga.App):
    def startup(self):
        # build UI

if __name__ == '__main__':
    app = MyApp('First App', 'org.pybee.helloworld', startup=build)

Supported Platforms

Component iOS win32 web django cocoa gtk android
App yes yes no yes yes yes yes


class, app_id, icon=None, id=None, startup=None, document_types=None)

The App is the top level of any GUI program. It is the manager of all the other bits of the GUI app: the main window and events that window generates like user input.

When you create an App you need to provide it a name, an id for uniqueness (by convention, the identifier is a “reversed domain name”.) and an optional startup function which should run once the App has initialised. The startup function typically constructs some initial user interface.

Once the app is created you should invoke the main_loop() method, which will hand over execution of your program to Toga to make the App interface do its thing.

Here is the absolute minimum App:

app = toga.App('Empty App', 'org.pybee.empty')

Instantiate a new application

  • name (str) – The name of the application
  • app_id (str) – The unique application identifier, the reversed domain name, e.g. ‘’
  • icon (str) – Icon for the application
  • id (str) – The DOM identifier for the app (optional)
  • startup (callable that expects a single argument of toga.App) – The callback method before starting the app, typically to add the components
  • document_types (list of str) – Document types

Add a new document to this app.

Parameters:doc – The document to add
app = None

The identifier for the app.

This is the reversed domain name, often used for targetting resources, etc.

Return type:str

The commands registered with this application.

Return type:CommandSet

Return the list of documents associated with this app.

Return type:list of str

Shut down the application


The DOM identifier for the app.

This id can be used to target CSS directives

Return type:str

Invoke the application to handle user input.

This method typically only returns once the application is exiting.


Add a new document to this app.

Parameters:fileURL (str) – The URL/path to the file to add as a document

Create and show the main window for the application