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

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

Embed the wheel version into the Go binary at compile time (requires a var version in your Go source):

go-to-wheel ./mytool --version 2.0.0 --set-version-var main.version

This passes -X main.version=2.0.0 to the Go linker, so the compiled binary knows its own version without hardcoding it in the Go source. A typical Go pattern for this:

var version = "dev"

func main() {
    if os.Args[1] == "--version" {
        fmt.Println(version) // prints "2.0.0" when built with --set-version-var
    }
}

Pass arbitrary Go linker flags with --ldflags:

go-to-wheel ./mytool --version 2.0.0 \
  --ldflags "-X main.version=2.0.0 -X main.commit=abc123"

The flags are appended to the default -s -w, so the full linker invocation becomes -ldflags="-s -w -X main.version=2.0.0 -X main.commit=abc123".

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 "jane@example.com" \
  --url "https://github.com/jane/mytool" \
  --readme README.md

Supported platforms

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