Install & Compatibility
Where this runs
tested against v2.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.686s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.586s · 19MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Extension
✓ from setuptools import Extension
setuptools-golang is configured via the 'setup()' function in setup.py, specifically through 'setup_requires' and the 'build_golang' dictionary, rather than direct imports of classes from the setuptools_golang package itself.
A `setup.py` demonstrating how to define a Go extension using `setuptools-golang`. The `build_golang` dictionary specifies the root Go import path, and `Extension` points to the Go source file(s). This example creates a simple Go function `Sum` that adds two integers, exposed to Python.
import os
from setuptools import setup, Extension
# Create a dummy Go source file for the example
with open('example.go', 'w') as f:
f.write("""
package main
import "C"
//export Sum
func Sum(a, b int) int {
return a + b
}
func main() {}
""")
setup(
name='my_go_extension',
version='0.1.0',
description='A Python extension in Go',
setup_requires=['setuptools-golang'],
build_golang={'root': 'github.com/user/project'},
ext_modules=[
Extension(
'my_go_extension.example',
['example.go'],
),
],
)
# To demonstrate usage, you would typically run:
# python setup.py build_ext --inplace
# Then in Python:
# import my_go_extension.example
# print(my_go_extension.example.Sum(1, 2))
Debug
Known issues
breakingThe project is officially deprecated and archived. The maintainer states that 'multiple go shared objects in a single process is not supported' and 'it likely broke in go 1.21 and there is no intention to fix it'. This means extensions built with setuptools-golang may not work with Go versions 1.21 and newer.fixConsider alternative methods for Python-Go interoperability (e.g., RPC, FFI directly, or gopy), or pin your Go version to < 1.21. For new projects, avoid this library.
affects: Go >= 1.21, setuptools-golang 2.x
gotchaWhen building extensions that involve C code (e.g., CGo), related C files might not be included in the distribution by default, leading to 'undefined reference' errors during linking.fixAdd `global-include *.c` to your `MANIFEST.in` file to ensure C source files are included alongside Go sources.
affects: All
gotchaIncorrect or non-existent external Go import paths can lead to 'fatal: could not read Username for 'https://github.com'' or 'package github.com/a/b/c: ... exists but .../.git does not' errors.fixDouble-check the correctness of your Go import paths. Ensure that all external dependencies are correctly vendored or accessible through the Go module system.
affects: All
gotchaDuplicate symbol errors (e.g., `duplicate symbol _XXX`) can occur if global variables defined in C code are not correctly marked for Go's CGo interaction.fixEnsure that global variables defined in your C code that are accessed by Go are marked with `extern`.
affects: All
gotchaRepeated builds can be slow due to Go's default GOPATH management.fixSet the `SETUPTOOLS_GOLANG_GOPATH` environment variable to reuse a consistent GOPATH, e.g., `$ SETUPTOOLS_GOLANG_GOPATH=~/go pip install .`
affects: All
Errors
Common errors & fixes
go: go.mod file not found in current directory or any parent directory
The Go build process initiated by setuptools-golang requires a go.mod file for module management, but it could not be found in the specified source directory.
fixInitialize a Go module in your Go source directory using `go mod init <module_name>` and ensure the `go_src` path in your `setup.py` points correctly to this directory.
distutils.errors.DistutilsExecError: command 'go' failed: No such file or directory
The 'go' executable is not installed on the system or is not included in the system's PATH environment variable, preventing setuptools-golang from executing the Go compiler.
fixInstall the Go toolchain and add its `bin` directory (e.g., `/usr/local/go/bin`) to your system's PATH environment variable.
ImportError: cannot import name '_C' from 'your_go_module'
This error occurs when Python fails to load the Go-built shared library because it was not successfully created, is not in an accessible location, or is missing expected internal symbols.
fixExamine the `setuptools-golang` build logs for any underlying Go compilation or linking errors. Verify that `go_src` and `mod_path` in your `setup.py` are correctly configured, and ensure all Go dependencies are properly managed (e.g., `go mod tidy`).
Upgrade
Version history
2.9.0latest on PyPI · released Jul 29, 2023
Audit
Dependencies
setuptoolsrequiredIt's an extension for setuptools.
golangrequiredRequires Go compiler (>= 1.5) to build extensions.