# briefcase-windows-app-template

**Repository Path**: mxiaoguang/briefcase-windows-app-template

## Basic Information

- **Project Name**: briefcase-windows-app-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-14
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# Briefcase Windows App Template

A
[Cookiecutter](https://github.com/cookiecutter/cookiecutter/)
template for building Python apps that will run under Windows, packaged
as an MSI installer.

## 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:

    ```text
    pip install cookiecutter
    ```

2. Run `cookiecutter` on the template:

    ```text
    cookiecutter https://github.com/beeware/briefcase-windows-app-template
    ```

   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`.

3. [Obtain a Python Windows Embeddable package](https://github.com/beeware/briefcase-windows-app-template#id1), and extract it into the
   `My Project/src` directory generated by the template. This will give you a
   `python3.dll` (amongst other artefacts) in the `My Project/src` folder.

4. Add your code to the template, into the `My Project/src/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 under the
   `My Project/src/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:

```text
My Project/
    src/
        app/
            my_project/
                __init__.py
                __main__.py
                app.py
        app_packages/
            ...
    python3.dll
    ...
    briefcase.toml
    my-project.ico
    my-project.wxs
    MyProject.exe
```

This project can now be compiled with
[WiX](https://wixtoolset.org)
to produce an MSI file. Open a command prompt, and change into the `My Project`
directory. Then:

```text
C:\...>wix build -ext WixToolset.UI.wixext -arch x64 my-project.wxs -loc unicode.wxl -o "My Project.msi"
```

The MSI file can then be used to install your application. When installed, your
application will have an entry in your Start menu.

## Next steps

Of course, running Python code isn't very interesting by itself - you won't
be able to do any console input or output, because a Windows app doesn't
display a console.

To do something interesting, you'll need to work with the native Windows system
libraries to draw widgets and respond to screen taps. The
[Python for .NET](https://pythonnet.github.io/)
bridging library can be used to interface with the Windows system libraries.
Alternatively, you could use a cross-platform widget toolkit that supports
Windows (such as [Toga](https://beeware.org/project/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.