Building Standalone Executables

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• setup.py
• pyproject.toml
• proxybroker/init.py

ProxyBroker2 supports the creation of standalone, one-file executables. This process bundles the Python interpreter, necessary dependencies, and internal data files into a single binary for distribution on Windows, Linux, and macOS. The build system uses PyInstaller and specific entry points to ensure all asynchronous components and data assets, such as the GeoIP database, are correctly included.

Sources: README.md:95-97, CLAUDE.md:204-205

Build Requirements and Environment

Building a standalone executable requires specific system utilities and Python packages. You must install these tools before starting the build process.

System Dependencies

For UNIX-like systems (Linux, macOS, BSD), the build process requires:

• upx: Used for executable compression.
• binutils: Specifically objdump, which is required for dependency analysis.

Sources: README.md:100-107

Python Dependencies

The project uses pyinstaller for the bundling process. You must also install the ProxyBroker2 package in editable mode or as a library to ensure all metadata and entry points are available to the builder.

Sources: README.md:112-113

Build Architecture and Workflow

The build process transforms the source code and its data assets into a portable binary. It utilizes py2exe_entrypoint.py as the main execution script rather than the standard module entry point.

Build Pipeline Logic

The following diagram illustrates the sequence of operations required to produce a functional standalone binary:

The build pipeline involves environment preparation, asset bundling, and final artifact isolation.
Sources: README.md:105-117

Key Build Parameters

The build command uses several critical flags to ensure the binary functions correctly:

Parameter	Description
--onefile	Bundles everything into a single executable file.
--name proxybroker	Sets the output filename of the executable.
--add-data	Includes the GeoIP data folder from proxybroker/data into the internal data path.
--workpath	Sets the temporary directory for build artifacts.
--distpath	Sets the final destination for the executable binary.

Sources: README.md:116

Internal Asset Management

ProxyBroker2 relies on bundled data files for core functionality, such as geolocation lookups. The build process must explicitly map these files so they are accessible at runtime within the compressed binary environment.

• GeoIP Database: The build includes proxybroker/data/*.mmdb files. These files provide geolocation data for discovered proxies.
• Entry Point: The system uses py2exe_entrypoint.py as the entry point for the executable, which differs from the standard python -m proxybroker module invocation used in development.

Sources: README.md:116, setup.py:46-47, pyproject.toml:10

Inclusion of Data Files

The setup.py and pyproject.toml files define which assets are considered part of the package. The builder respects these definitions to ensure the binary is functional.

# From setup.py
PACKAGES = ["proxybroker", "proxybroker.data"]
PACKAGE_DATA = {"": ["LICENSE"], INFO["package"]: ["data/*.mmdb"]}

Sources: setup.py:44-46

Execution Commands

To build the executable, run the following sequence of commands in your terminal:

# 1. Install pyinstaller and the local package
pip install pyinstaller && pip install .

# 2. Prepare build directory and execute bundling
mkdir -p build && cd build
pyinstaller --onefile --name proxybroker \
    --add-data "../proxybroker/data:data" \
    --workpath ./tmp --distpath . --clean \
    ../py2exe_entrypoint.py

# 3. Cleanup build artifacts
rm -rf tmp *.spec

Sources: README.md:112-117

Summary

Building standalone executables for ProxyBroker2 allows for easy distribution across different operating systems without requiring a local Python installation on the target machine. By bundling the internal GeoIP database and using a specific entry point script, the resulting binary retains the full capabilities of the asynchronous proxy finder, checker, and server.

Sources: README.md:95-97, CLAUDE.md:204-205