Skip to main content

An example of Python application distribution.

Project description

Python Distribution Example

This repository accompanies this series of articles about developing a portable Python application that can be installed and run without any external dependencies.

This is useful for distributing Python applications to users without a Python environment, or for distributing a Python application via package managers.


These steps only need to be completed on first-time setup.

Install Dependencies

  • Python >=3.8, <3.13

Refer to release.yaml for platform-specific installer dependencies. The installer builds for Windows, Linux, and MacOS run on GitHub runners, so you don't need to install the requirements unless you are troubleshooting a platform-specific installer build script.

Clone this Repository

If you'd like to track your own changes in GitHub, then you should fork this repository, and then clone your fork.

git clone

Install the Python venv

  • change directory to the root of the cloned repository:
    cd python-distribution-example
  • create the venv
    python3 -m venv .venv
    or, if python points to your desired Python 3 version:
    python -m venv .venv

    The venv is installed to .venv After the venv is activated, python is the preferred alias to the Python installed in the venv

  • activate the development environment
    . ./envr.ps1

    envr will activate your venv

  • install Python dependencies to the venv, including the optional dev dependencies
    pip install --require-virtualenv -e .[dev]

    You must instruct users to run this step whenever the Python dependencies change.


Make sure to complete the setup first.

Activate the Development Environment

This step is required before running or building the app.

. ./envr.ps1

Now you can run the app within the Python venv:

jpsapp --help

Build the sdist and wheel

python -m build

The build output is at dist/.

Build the Portable App for Your Host Platform

python -m distribution.portable

The build output is at dist/jpsapp-<version>-<platform>-<arch>, e.g. dist/jpsapp-1.0.0-windows-amd64, as well is in a ZIP archive of the same name.

Tools Used

  • GitHub Actions: automate the build and release of the application on GitHub runners.
  • envr: manage environment variables, PATH, and Python venv.
  • build: A simple, correct Python packaging build frontend.
  • PyInstaller: create a "one-dir" portable "executable" of the Python application
  • WiX v4: create a Windows installer, *.msi, that creates a double-clickable version of the app, adds the app to the system PATH, adds an app folder to the Start Menu, and optionally adds a shortcut to the desktop.
  • FPM: create *.deb and *.rpm Linux packages that install the app to /usr/share/ and add a symlink to /usr/bin/*.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jpsapp-1.1.10.tar.gz (12.5 kB view hashes)

Uploaded Source

Built Distribution

jpsapp-1.1.10-py3-none-any.whl (12.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page