Skip to main content

Generate standalone python applications.

Project description

License Build Status Python Version Compatibility Version Pull Reminder

GravityBee helps you generate standalone applications for Windows, Mac, and Linux from your Python applications.

GravityBee is targeted at Python programs that are already packaged in the standard setuptools way.

These are some benefits of a GravityBee standalone application:

  • You end up with one file that contains everything.

  • Your users do not need Python or any packages installed.

  • You build separate natively executable applications for each of your target platforms.

GravityBee depends on Pyppyn and PyInstaller and is subject to their limitations.

To Build A Standalone Application

Step 1 - Install

You must install the application you wish to build (e.g., yoursuperapp), as well as GravityBee.

$ pip install yoursuperapp gravitybee

The process will also work fine if you’re installing from a local version of your app.

$ cd yoursuperapp
$ ls setup*
$ pip install --editable .
$ pip install gravitybee

Step 2 - Provide (or gather) information

GravityBee will assume all necessary information when run. However, you may wish to override the assumed values. You can provide values either through environment variables or command line flags. If both are provided, command line flags take precedence.

Local logging can be configured in gravitybee/logging.conf.



CL Options



–app-name, -a

The name that will appear as part of the final standalone application name. Default: name from and/or setup.cfg.


–pkg-name, -n

The package name for the application you are building. Default: First value in packages from and/or setup.cfg, or if not found, the value from –app-name.


–script, -s

The path to the application file installed by pip when you installed your application. Depending on your configuration, this may be determined by options.entry_points.console_scripts from and/or setup.cfg. Default: $VIRTUAL_ENV/bin/app_name


–src-dir, -d

The relative path of the package containing your application. Default: .


–pkg-dir, -p

The relative or absolute path of the package containing your application. This directory must contain a file. Default: .


–extra-data, -e

Relative to package directory, any extra directories or files that need to be included, that wouldn’t normally be included as Python code. Can be used multiple times. Default: None


–work-dir, -w

Directory for use by GravityBee to build application. Cannot be an existing directory as it will be deleted if the clean voption is used. Default: .gravitybee/build/<uuid>



Instead of packaging into one file, package in one directory. This option is not compatible with producing a SHA hash since a hash is produced on a single file. This option may be useful for debugging runtimes errors in built applications. Default: Not


–clean, -c

Flag indicating whether to clean up the work directory after the build. Default: Not


–name-format, -f

Format to be used in naming the standalone application. Can include {an}, {v}, {os}, {m} for app name, version, os, and machine type respectively. On Windows, .exe will be added automatidally. Default: {an}-{v}-standalone-{os}-{m}



Format to be used in naming the SHA hash file. Can include {an}, {v}, {os}, {m} for app name, version, os, and machine type respectively. Default: {an}-{v}-sha256-{os}-{m}.json



Format to be used in labeling the standalone application in gravitybee-files.json. Can include {An}, {an}, {v}, {os}, {m}, and {ft} for capitalized application name, lowercase app name, version, OS, machine, and file type (“Standalone Executable” or “Standalone Executable SHA256 Hash”) respectively. On Windows, .exe will be added automatically. Default: {An} {v} {ft} for {os} [GravityBee Build]



Flag indicating to not write the output files (see below). If the --sha option is used to write a hash to a file, that file will still be written regardless. Default: Will write files



Option of where to put SHA256 hash for generated file. Valid options are file (create a separate file with hash), or info (only include the hash in the file info output). Default: info



Option to indicate where GravityBee should stage build artifacts (standalone executable and hash file). Two subdirectories can be created, one based on version and the other called “latest.” Default: .gravitybee/dist



Flag to indicate if GravityBee should create a “latest” directory in the staging area with a copy of the artifacts. Default: Not



Includes any ‘extras’ modules listed in standalone application. (Such as packages marked ‘build’, ‘docs’, ‘check’, etc.) Default: False



Any extra modules to be included with the standalone executable. Default: None



Any extra packages to be included with the standalone executable. Default: None


If using conda env set VIRTUAL_ENV to conda env directory

If you are using environment variables, you could set them up like this.

$ export GB_APP_NAME=coolapp
$ export GB_PKG_NAME=coolapp
$ export GB_SCRIPT=/usr/var/python/etc/coolapp

Step 3 - Generate

Creating the standalone application is easy now.

$ gravitybee

If you are not using environment variables, you can combine steps 2 and 3.

$ gravitybee --app-name coolapp --script /usr/var/python/etc/coolapp --pkg-dir coolapp

Output Files

If the --no-file flag is not used, GravityBee will create output files. These include:

  • gravitybee-files.json: A JSON file that contains information about the standalone application generated by GravityBee including filename, path, mime-type, and label as a list of dicts.

  • gravitybee-info.json: A JSON file that contains information extracted about the application including app_name, app_version, console_script, script_path, pkg_dir, src_dir, name_format, clean, work_dir, gen_file, gen_file_w_path, and extra_data.

  • A shell file that can be sourced on POSIX platforms to create environment variables with GravityBee information. Each is prefixed with GB_ENV_.

  • gravitybee-environs.bat: A batch file that can be used to create environment variables with GravityBee information on Windows. Each environ is prefixed with GB_ENV_.

The Test Example

Here is the file/package structure of the included test application.

|-- setup.cfg
>-- src
|   >-- gbtestapp
|       |--
|       |--
|       >-- gbextradata
|           |--
|           |-- data_file.txt

You would build the application as follows. Since the application package is under the src directory, you need to let GravityBee know. Also, since we need to include the data_file.txt file, we’ll use the --extradata option to include the containing directory (gbextradata).

$ cd gbtestapp
$ gravitybee --src-dir src --extra-data gbextradata --clean

From Python Example

Using GravityBee from a Python script is also possible. Using the sample test app, here’s some example code.

import gravitybee

args = gravitybee.Arguments(
    pkg_dir=os.path.join("tests", "gbtestapp"),

pg = gravitybee.PackageGenerator(args)

# show path (and name) of standalone app
print("The standalone app: ", pg.gen_file_w_path)


The idea for GravityBee’s core functionality comes from Nicholas Chammas and his project flintrock. Huge thanks to Nicholas!


GravityBee is hosted on GitHub and is an open source project that welcomes contributions of all kinds from the community.

For more information about contributing, see the contributor guidelines.


0.3.0 - 2022.04.21

  • [DEPRECATION] Deprecates Python 3.6 support.

0.2.0 - 2021.08.02

  • [FEATURE] Add option –hook-template that allows user to specify their own hook template for PyInstaller.

  • [FIX] Update the included hook-template to work correctly when the pkg_name and app_name are different.

0.1.29 - 2020.01.15

  • [ENHANCEMENT] Remove pipenv files and update setup.cfg dependency versions.

0.1.28 - 2020.01.14

  • [ENHANCEMENT] Bump version to include updated dependencies.

0.1.27 - 2019.05.06

  • [ENHANCEMENT] Bump version to include updated dependencies.

0.1.26 - 2019.02.05

  • [ENHANCEMENT] Fix distutils issue, improve error handling, update versions.

0.1.25 - 2019.01.31

  • [ENHANCEMENT] Add distutils to builds.

0.1.24 - 2019.01.29

  • [ENHANCEMENT] Clean up code, add community docs.

  • [ENHANCEMENT] Transfer to Plus3IT.

0.1.23 - 2019.01.24

  • [FIX] Properly pin Pip so all dependencies are installed with pinned Pip version.

  • [ENHANCEMENT] Restructure Travis CI linting, testing, deploying so deploy only happens when other stages complete successfully.

  • [ENHANCEMENT] Improve speed of MacOS builds significantly.

0.1.22 - 2019.01.22

  • [ENHANCEMENT] Pin Pip and Pytest versions, adding requirements.txt.

0.1.21 - 2019.01.10

  • [ENHANCEMENT] Lint code to conform with pylint and flake8 and add them Travis-CI tests.

  • [ENHANCEMENT] Use pipenv and a lock file for dependency management.

  • [ENHANCEMENT] Adjust for compatibility with Python 3.7.

0.1.20 - 2018.08.08

  • [ENHANCEMENT] Add --label-format option so that users can customize the label displayed for their applications in gravitybee-files.json.

0.1.19 - 2018.07.11

  • [ENHANCEMENT] Add --extra-pkgs and --extra-modules options for including additional packages and modules with standalone executables.

0.1.18 - 2018.07.05

  • [ENHANCEMENT] Add --onedir flag for improved debugging.

0.1.17 - 2018.06.27

  • [FIX] Compatibility issues with CentOS 6 resolved.

0.1.16 - 2018.06.21

  • [FIX] Compatibility issues with Windows resolved.

0.1.15 - 2018.06.06

  • [FIX] Losing .exe extension with Windows executables in the latest staging area.

0.1.14 - 2018.06.04

  • [FIX] --with-latest was not working as a CL flag.

0.1.13 - 2018.06.04

  • [ENHANCEMENT] Rearrange files created by GravityBee to all be contained in a .gravitybee subdirectory of the current directory.

  • [ENHANCEMENT] Place the distribution artifacts in the staging directory, with a default value of .gravitybee/dist.

  • [ENHANCEMENT] Add option --staging-dir to specify directory where artifact staging should take place and export another environment variable GB_ENV_STAGING_DIR.

  • [ENHANCEMENT] Add option --with-latest to allow creation of a second artifact staging directory called “latest” containing the artifacts renamed with “latest” in the place of the version.

  • [ENHANCEMENT] Add option --sha-format to allow custom naming of the SHA hash file.

0.1.12 - 2018.05.29

  • [ENHANCEMENT] Add OS and machine type to the SHA256 hash file (to avoid overwriting files if files from different platforms go to the same location).

  • [ENHANCEMENT] Cleanup code with better variable names.

0.1.11 - 2018.05.24

  • [ENHANCEMENT] Create a SHA256 hash for the generated standalone file and include hash with file information and optionally in a separate file (using –sha flag).

  • [ENHANCEMENT] Change names of environment variables produced with output scripts to be prefixed with GB_ENV so that the environs do not collide with environs consumed by GravityBee.

  • [ENHANCEMENT] Provide a convenience cleanup Bash script to remove GravityBee output files (e.g., json and generated executables).

  • [ENHANCEMENT] Cleanup code with more constants.

0.1.10 - 2018.05.21

  • [ENHANCEMENT] Provide two additional output files for importing GravityBee information into the environment on POSIX and Windows platforms.

0.1.9 - 2018.05.14

  • [ENHANCEMENT] Output file with run info in json format for easy consumption by other tools.

0.1.8 - 2018.05.11

  • [ENHANCEMENT] In non-verbose mode, allow for supressing stdout and stderr from pyinstaller, which can be sizeable.

  • [ENHANCEMENT] Change name of gravitybee.file to gravitybee-files.json.

0.1.7 - 2018.05.11

  • [FIX] Fix exit code (was returning True).

  • [ENHANCEMENT] Automatically find console script installed by setuptools on Windows and Linux and variety of places.

0.1.6 - 2018.05.03

  • [ENHANCEMENT] Follow format prescribed by satsuki for output file (potential for multiple files).

0.1.5 - 2018.05.01

  • [ENHANCEMENT] Add mime-type and label to .json formatted file information stored in gravitybee.file.

0.1.3 - 2018.05.01

  • [ENHANCEMENT] Create gravitybee.file with name of standalone application.

0.1.2 - 2018.04.27

  • [ENHANCEMENT] Provide standalone file and path.

  • [FIX] Path bug.

0.1.1 - 2018.04.26

  • [FIX] Many bug fixes.

0.1.0 - 2018.04.20

  • Initial release!

Project details

Release history Release notifications | RSS feed

This version


Download files

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

Source Distribution

gravitybee-0.4.6.tar.gz (36.6 kB view hashes)

Uploaded source

Built Distribution

gravitybee-0.4.6-py2.py3-none-any.whl (22.1 kB view hashes)

Uploaded py2 py3

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