go-to-wheel 0.1

Compile Go CLI programs into Python wheels

go-to-wheel

Compile Go CLI programs into Python wheels.

This tool takes a Go module directory, cross-compiles it for multiple platforms, and produces properly-tagged Python wheels that can be installed via pip or pipx to get the Go binary on your PATH.

Installation

pip install go-to-wheel
# or
pipx install go-to-wheel

Requires Go to be installed and available in your PATH.

Quick start

Build wheels for all platforms from a Go module:

go-to-wheel path/to/go-module

This will create wheels in a ./dist directory for Linux (glibc and musl), macOS (Intel and Apple Silicon), and Windows (amd64 and arm64).

Usage

go-to-wheel path/to/go-folder [options]

Options

Option	Description	Default
--name NAME	Python package name	Directory basename
--version VERSION	Package version	0.1.0
--output-dir DIR	Directory for built wheels	./dist
--entry-point NAME	CLI command name	Same as package name
--platforms PLATFORMS	Comma-separated list of targets	All supported platforms
--go-binary PATH	Path to Go binary	go
--description TEXT	Package description	"Go binary packaged as Python wheel"
--license LICENSE	License identifier	None
--author AUTHOR	Author name	None
--author-email EMAIL	Author email	None
--url URL	Project URL	None
--requires-python VERSION	Python version requirement	>=3.10

Examples

Build wheels with a custom package name:

go-to-wheel ./mytool --name my-python-tool

Build for specific platforms only:

go-to-wheel ./mytool --platforms linux-amd64,darwin-arm64

Build with full metadata for PyPI:

go-to-wheel ./mytool \
  --name mytool-bin \
  --version 2.0.0 \
  --description "My awesome tool" \
  --license MIT \
  --author "Jane Doe" \
  --author-email "[e-mail]" \
  --url "https://github.com/jane/mytool"

Supported platforms

Platform	Wheel Tag
linux-amd64	manylinux_2_17_x86_64
linux-arm64	manylinux_2_17_aarch64
linux-amd64-musl	musllinux_1_2_x86_64
linux-arm64-musl	musllinux_1_2_aarch64
darwin-amd64	macosx_10_9_x86_64
darwin-arm64	macosx_11_0_arm64
windows-amd64	win_amd64
windows-arm64	win_arm64

How it works

1. Cross-compiles the Go binary using GOOS and GOARCH environment variables with CGO_ENABLED=0 for static binaries
2. Creates a Python package with a thin wrapper that execs the bundled binary
3. Packages everything into a wheel with the correct platform tag

The resulting wheel can be installed with pip:

pip install ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl

Or tested directly with uv:

uv run --with ./dist/mytool-1.0.0-py3-none-manylinux_2_17_x86_64.whl mytool --help

Development

Clone the repository:

git clone https://github.com/simonw/go-to-wheel
cd go-to-wheel

Run tests:

uv run pytest

See also

• maturin - The Rust equivalent that inspired this tool
• pip-binary-factory - Template for packaging pre-built binaries