DOCSEARCHbyAlgolia
Submit Docs

PyApp

repository·master·Indexed 24 days ago

https://github.com/ofek/pyapp

A runtime installer for Python applications that wraps them into standalone, platform-specific binaries. PyApp manages the Python environment and application execution, supporting features such as standalone binary builds, configurable runtime behavior, and optional management commands for self-updates. It allows for flexible Python distribution sourcing (CPython, PyPy, or custom), embedding of distributions and projects, and installation via pip or uv.

Tokens
6.1K
Snippets
4
Records
60
Agent score
84%

What's inside pyapp

  1. What is PyApp

    master
    PyApp is a wrapper for Python applications that bootstraps them at runtime. It allows you to build standalone binaries for various platforms, providing a seamless experience where the user runs a single executable that manages the Python environment and application execution.

  2. Detect if an application is running via PyApp

    master
    You can detect if your application is being run through the PyApp bootstrap process by checking for the presence of the PYAPP environment variable. When running applications, PyApp injects PYAPP=1 by default.

  3. Configure runtime installation sources

    master

    PyApp supports three ways to configure how the project is installed at runtime. Note that the project identifier is required in all cases.

    1. Package Index (PyPI)

    By providing only PYAPP_PROJECT_NAME and PYAPP_PROJECT_VERSION, the package will be installed from a package index like PyPI.

    2. Dependency File

    You can install your project using a local requirements file by setting PYAPP_PROJECT_DEPENDENCY_FILE to the local path of the file. Supported extensions are .txt and .in (standard requirements file format). In this mode, the project identifier is used only as metadata and not for installation.

    3. Embedding

    You can embed a specific package directly into the binary by setting PYAPP_PROJECT_PATH to a path pointing to a .whl (wheel) or a .tar.gz (source distribution) file. When embedding, the project identifier is automatically derived from the metadata inside the file.

  4. Key features of PyApp

    master

    PyApp provides the following capabilities:

    • Standalone Binaries: Easily build binaries for every platform.
    • Management Commands: Optional commands for functionality like self-updates.
    • Configurable Runtime: Extremely configurable runtime behavior to target different end-user requirements.

  5. Install PyApp via Cargo

    master

    You can install the pyapp binary directly using Cargo. Use the --root option to specify the installation directory. You can also specify a version using the --version flag.

    Note: Cross-compilation is currently unsupported via the cargo install method.

    Output Locations:

    • Windows: <DIR>/bin/pyapp.exe
    • Other OS: <DIR>/bin/pyapp

  6. Build PyApp applications

    master

    Once you have configured the necessary environment variables, use Cargo to build the release binary. The resulting executable will be located in the target/release/ directory.

    cargo build --release

  7. Embed a Python distribution in the executable

    master

    To avoid fetching a Python distribution at runtime, you can embed it directly into the executable at build time.

    There are two ways to achieve this:

    1. Using PYAPP_DISTRIBUTION_EMBED: Set this to true or 1.
    2. Using PYAPP_DISTRIBUTION_PATH: Set this to a local path pointing to a Python archive. This implicitly enables embedding.

    The local archive should be structured similarly to the default distributions and contain a ready-to-use Python interpreter.

  8. Build PyApp from a local repository

    master

    To build PyApp from source, first ensure your project is configured according to the project configuration guide. Download the source archives from the releases page (e.g., source.tar.gz). After unpacking, run the build command from the repository root.

    Output Locations:

    • Windows: target/release/pyapp.exe
    • Other OS: target/release/pyapp
    • Cross-compiled/Specific Target: target/<TARGET>/release/pyapp (or .exe on Windows)

  9. Cross-compiling PyApp

    master

    Cross-compilation is supported using cross.

    Important Requirement for Embedding: If you are embedding a project or distribution using a local path, you cannot use cargo install. You must use the Local Repository build method. Additionally, ensure that:

    1. The files to be embedded reside within the repository.
    2. The configuration options use relative paths.

  10. Get PyApp source code

    master

    To build applications with PyApp, you must download the source code. Follow these steps based on your operating system to download and extract the latest release.

    Linux/macOS

    1. Download the source tarball using curl.
    2. Extract the archive.
    3. Rename the extracted directory to pyapp-latest.
    4. Enter the directory.

    Windows

    1. Download the source zip using Invoke-WebRequest.
    2. Extract the archive using 7z.
    3. Rename the extracted directory to pyapp-latest.
    4. Enter the directory.
    # Linux/macOS
curl https://github.com/ofek/pyapp/releases/latest/download/source.tar.gz -Lo pyapp-source.tar.gz
tar -xzf pyapp-source.tar.gz
mv pyapp-v* pyapp-latest
cd pyapp-latest

# Windows (PowerShell)
Invoke-WebRequest https://github.com/ofek/pyapp/releases/latest/download/source.zip -OutFile pyapp-source.zip
7z x pyapp-source.zip
mv pyapp-v* pyapp-latest
cd pyapp-latest

  11. Distribute the built binary

    master

    After building, rename the pyapp binary to your application's name. On non-Windows systems, you must also ensure the file has executable permissions.

    Linux/macOS

    mv target/release/pyapp cowsay && chmod +x cowsay

    Windows

    mv target\release\pyapp.exe cowsay

  12. Use a custom Python distribution source

    master

    To use a Python distribution not included in the known list, set the PYAPP_DISTRIBUTION_SOURCE option to a URL pointing to an archived version of the desired distribution.

    Note: Manually setting the source may require defining additional metadata (such as paths) to ensure correct runtime behavior.