Creating a PyOxidizer Project

The process for oxidizing every Python application looks the same: you start by creating a new PyOxidizer configuration file via the pyoxidizer init-config-file command:

# Create a new configuration file in the directory "pyapp"
$ pyoxidizer init-config-file pyapp

Behind the scenes, PyOxidizer works by leveraging a Rust project to build binaries embedding Python. The auto-generated project simply instantiates and runs an embedded Python interpreter. If you would like your built binaries to offer more functionality, you can create a minimal Rust project to embed a Python interpreter and customize from there:

# Create a new Rust project for your application in ~/src/myapp.
$ pyoxidizer init-rust-project ~/src/myapp

The auto-generated configuration file and Rust project will launch a Python REPL by default. And the pyoxidizer executable will look in the current directory for a pyoxidizer.bzl configuration file. Let’s test that the new configuration file or project works:

$ pyoxidizer run
...
   Compiling pyapp v0.1.0 (/home/gps/src/pyapp)
    Finished dev [unoptimized + debuginfo] target(s) in 53.14s
writing executable to /home/gps/src/pyapp/build/x86_64-unknown-linux-gnu/debug/exe/pyapp
>>>

If all goes according to plan, you just built a Rust executable which contains an embedded copy of Python. That executable started an interactive Python debugger on startup. Try typing in some Python code:

>>> print("hello, world")
hello, world

It works!

(To exit the REPL, press CTRL+d or CTRL+z or import sys; sys.exit(0) from the REPL.)

Note

If you have built a Rust project before, the output from building a PyOxidizer application may look familiar to you. That’s because under the hood Cargo - Rust’s package manager and build system - is doing a lot of the work to build the application. If you are familiar with Rust development, you can use cargo build and cargo run directly. However, Rust’s build system is only responsible for build binaries and some of the higher-level functionality from PyOxidizer’s configuration files (such as application packaging) will likely not be performed unless tweaks are made to the Rust project’s build.rs.

Now that we’ve got a new project, let’s customize it to do something useful.