PyCrucible: An easy way to redistribute your Python apps

One of Python’s most persistent limitations is how unnecessarily difficult it is to take a Python program and give it to another user as a self-contained click-to-run package. The design of the Python language makes this surprisingly difficult to do. Traditionally, the only reliable way to make it happen was to bundle the entire Python runtime, and all your program’s dependencies, along with the program.

This approach has two downsides. First, the resulting redistributable is quite large, and hard to slim down because of Python’s inherent dynamism. Second, third-party programs distributed this way can take lots of tinkering to work right.

Now we’re seeing a new generation of tooling—some powered by Rust and the culture of Rust-based Python utilities—that solves the age-old Python distribution problem in various ways. These tools don’t address the problem of size—that’s a toughie—but they do streamline the packaging process, making it almost as easy to bundle a Python app as it is to click-to-launch it.

Also see: PyApp: An easy way to package Python apps as executables.

One of the new projects in this vein is PyCrucible. Its feature set is minimal, but that also means it’s surprisingly easy to set up and work with.

Setting up PyCrucible

If you want to use PyCrucible to package a given Python project, you’ll need a few things.

Your Python project must be set up as a ‘pip install’-able package with a pyproject.toml file. This is the single biggest requirement: your project must be set up in such a way that it follows the guidelines detailed in the Python Packaging Authority documentation.

Your project must have an entry point. Most projects have an explicitly defined entry point—a module or function that’s the default thing to run. PyCrucible requires one defined in advance so it knows how to start your program.

You must have PyCrucible installed. This is the easy part, as all it involves is running pip install pycrucible in the virtual environment for your project.

Configuring a project for PyCrucible

The one step you’ll need to take to make your project work with PyCrucible is to add the following section to your pyproject.toml file:

[tool.pycrucible]
entry = 'main.py'

This describes the file, or module, that’s the entry point for your project. Note that the path to that module should be described relative to the root of the project. For instance, if your entry point was at src/mytool/main.py, you’d use entry = 'src/mytool/main.py' to indicate it.

Packaging a project with PyCrucible

The actual packaging process is also straightforward. In the activated venv where you installed PyCrucible, go to the directory where your project lives and type:

pycrucible -e. -o.exe

where is the name you want for the resulting redistributable. (You’d use.exe for Microsoft Windows.)

The -e flag embeds (e for embed) the project in the current working directory (hence the.), and outputs (-o) the result to the file you specify. The packaging process is entirely self-guided: it uses your project’s standard installation behaviors—whatever would happen if you pip install-ed the project into a venv—to create the redistributable package.

Once the packaging process finishes, you’ll see a new file with the chosen name appear in that directory. There are no other artifacts created; you can take that file and redistribute it as you see fit.

Running a PyCrucible-packaged project

All someone else needs to run your PyCrucible-packaged project is the generated artifact. They do not need to install Python, or any other compiler or runtime elements.

When the executable first runs, it creates a subdirectory named pycrucible_payload, extracts all the needed files into it, and then launches the program from there. On subsequent runs, if the pycrucible_payload directory already exists, it’ll skip the extraction step and just run the extracted program.

Because of this, one important restriction with using a PyCrucible project is it must be launched in a directory where the user has write permissions. But this rarely poses an obstacle.

Advanced PyCrucible settings

PyCrucible projects have a few advanced options that can be set when a project is bundled. To set these behaviors, you’ll need to add a section to pyproject.toml:

[tool.pycrucible.options]
extract_to_temp = true
delete_after_run = true

When set to true, extract_to_temp has the extracted files placed in and run from a system- or user-level temporary directory. The delete_after_run setting causes the extracted files (wherever they’re extracted to) to be removed after the program runs. These options are useful for something that is only intended to run once—for instance, as a stub to set up a larger program—or for something that isn’t likely to be run often and doesn’t need to be persistently available.