# briefcase-linux-appimage-template

**Repository Path**: mirrors_beeware/briefcase-linux-appimage-template

## Basic Information

- **Project Name**: briefcase-linux-appimage-template
- **Description**: A template for generating Linux AppImage projects with Briefcase
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-02-27
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Briefcase Linux AppImage Template
A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for
building Python apps that will run under Linux, packaged as an AppImage.

## Using this template
The easiest way to use this project is to not use it at all - at least, not
directly. [Briefcase](https://github.com/beeware/briefcase/) is a tool that
uses this template, rolling it out using data extracted from a `pyproject.toml` configuration file.

However, if you *do* want use this template directly...

1. Install [cookiecutter](https://github.com/cookiecutter/cookiecutter/). This is a tool used to bootstrap complex project templates:
```
    $ pip install cookiecutter
```

2. Run `cookiecutter` on the template:

```
    $ cookiecutter https://github.com/beeware/briefcase-linux-appimage-template
```
<ul>
   This will ask you for a number of details of your application, including the
   `name` of your application (which should be a valid PyPI identifier), and
   the `Formal Name` of your application (the full name you use to describe
   your app). The remainder of these instructions will assume a `name` of
   `my-project`, and a formal name of `My Project`.
</ul>

3. [Obtain a Python Standalone Build for x86_64](https://github.com/astral-sh/python-build-standalone/releases), and extract it into
   the `My Project/My Project.AppDir/usr` directory generated by the
   template. This will give you a self-contained Python install. If installed
   correctly, there should be a `My Project/My
   Project.AppDir/usr/bin/python3` binary, as well as some other
   Python-related files.

4. Add your code to the template, into the `My Project/My Project.AppDir/usr/app`
   directory. At the very minimum, you need to have an
   `app/<app name>/__main__.py` file that defines an entry point that will
   start your application.

   If your code has any dependencies, they should be installed into the
   `My Project/My Project.AppDir/usr/app_packages` directory.

If you've done this correctly, a project with a formal name of `My Project`,
with an app name of `my-project` should have a directory structure that
looks something like:
```
    My Project/
        My Project.AppDir/
            usr/
                app/
                    my_project/
                        __init__.py
                        __main__.py
                        app.py
                app_packages/
                    ...
                bin/
                    python3
                    ...
                lib/
                    ...
                share/
                    ...
            com.example.my-project.desktop
        briefcase.toml
```

This directory can then be compiled into an AppImage using [linuxdeploy](https://github.com/linuxdeploy/linuxdeploy).
Download the [linuxdeploy AppImage](https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage), and make the binary executable:
```
    $ chmod +x linuxdeploy-x86_64.AppImage
```

Then compile your AppDir directory (substituting your release version number):
```
    $ VERSION=1.2.3 ./linuxdeploy-x86_64.AppImage --appdir=My\ Project/My\ Project.AppDir -o appimage -d My\ Project/My\ Project.AppDir/com.example.my-project.desktop
```
This will produce `My Project-1.2.3-x86_64.AppImage`. This image can given
to any other Linux user, and should run without installing any other
dependencies.

## Next steps
Of course, running Python code isn't very interesting by itself.

To do something interesting, you'll need to work with the native system
libraries to draw widgets and respond to user input. The [GTK+](https://python-gtk-3-tutorial.readthedocs.io/) GUI library
provides Python bindings that you can use to build a user interface.
Alternatively, you could use a cross-platform widget toolkit that supports
Windows (such as [Toga](https://beeware.org/project/projects/libraries/toga)) to provide a GUI for your application.

If you have any external library dependencies (like Toga, or anything other
third-party library), you should install the library code into the
`app_packages` directory. This directory is the same as a  `site_packages`
directory on a desktop Python install.