go-to-wheel

February 10, 2026 · View on GitHub

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.

See Distributing Go binaries like sqlite-scanner through PyPI using go-to-wheel for background on this project.

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`
`--readme PATH`	Path to README markdown file for PyPI long description	None
`--set-version-var VAR`	Go variable to set to `--version` value via `-X` ldflag	None
`--ldflags FLAGS`	Additional Go linker flags (appended to default `-s -w`)	None

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

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

Cross-compiles the Go binary using GOOS and GOARCH environment variables with CGO_ENABLED=0 for static binaries
Creates a Python package with a thin wrapper that execs the bundled binary
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