Uppie

Uppie is a small Python library for adding GitHub Releases based auto-update checks to desktop applications.

It can:

• read the latest release from a public GitHub repository;
• compare the remote release version with the local application version;
• select a compatible release asset for the current platform;
• download the selected update asset with progress tracking;
• start the installer on Windows or open the downloaded DMG on macOS.

Supported release assets

Uppie selects assets by file name and current platform:

• Windows: .exe
• macOS: .dmg
• Linux: .AppImage

On macOS it also looks for architecture hints in the asset name. Apple Silicon builds can include words such as arm64, silicon, or apple; Intel builds can include intel, x86_64, or amd64. If no architecture-specific asset is found, Uppie falls back to a universal .dmg when available.

Installation

Install the latest version directly from GitHub:

python3 -m pip install git+https://github.com/SimoneDeAngelis95/uppie.git

Usage

from uppie import Uppie

updater = Uppie(
    repo_owner="your-github-user-or-org",
    repo_name="your-repository",
    local_version="v1.0.0",
)

if updater.is_update_available():
    updater.update()

API overview

Uppie(repo_owner, repo_name, local_version, download_folder=None)

Creates an updater for a GitHub repository.

• repo_owner: GitHub user or organization that owns the repository.
• repo_name: GitHub repository name.
• local_version: the version currently running in your application.
• download_folder: optional destination folder for downloaded update files.

If download_folder is omitted, Uppie stores downloads in:

• %APPDATA%/Uppie/downloads on Windows;
• ~/Downloads on macOS and Linux.

is_update_available() -> bool

Fetches the latest GitHub release and returns True only when:

• the latest remote version is newer than local_version;
• the latest release contains a compatible asset for the current platform.

When it returns True, Uppie also stores the selected asset URL internally for the later download step.

update() -> bool

Runs the complete update flow:

1. check whether an update is available;
2. download the selected release asset;
3. start the installer on Windows or open the DMG on macOS.

Returns True when the update file was opened or started, otherwise False.

On Windows, Uppie starts the downloaded .exe and removes it after the installer process exits. On macOS, Uppie leaves the downloaded DMG in place because the user installs the app manually from the mounted image.

get_progress_percentage() -> int

Returns the current download progress percentage.

Version format

Uppie accepts simple version strings such as:

• 1.2.3
• v1.2.3
• V10.0-beta

Version strings are normalized to integer tuples before comparison.

Release requirements

For Uppie to find an update, your GitHub repository must have a published latest release with a version-like tag or release name, for example v1.2.0.

Attach at least one update asset matching the platforms you support:

MyApp-1.2.0-windows.exe
MyApp-1.2.0-macos-arm64.dmg
MyApp-1.2.0-macos-intel.dmg
MyApp-1.2.0-linux.AppImage

macOS DMG behavior

On macOS, Uppie opens the downloaded DMG with the system open command. The user can then install the .app manually, usually by dragging it into /Applications.

Make sure the asset you publish matches the install flow expected by your app.

License

Uppie is distributed under the GNU General Public License v3.0. See LICENSE for details.