Setuptools Golang Extension

2.9.0 · deprecated · verified Sat Apr 11

setuptools-golang is a setuptools extension designed for building CPython extensions written in Go. It enables developers to integrate Go-based modules directly into Python packages. The library is currently at version 2.9.0, but its GitHub repository was archived in January 2025, indicating it is no longer actively maintained. The primary maintainer has stated that multiple Go shared objects in a single process are not supported by Go 1.21+ and there is no intention to fix this, severely limiting its utility with modern Go versions.

Warnings

breaking The 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.
Fix: Consider 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.
gotcha When 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.
Fix: Add `global-include *.c` to your `MANIFEST.in` file to ensure C source files are included alongside Go sources.
gotcha Incorrect 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.
Fix: Double-check the correctness of your Go import paths. Ensure that all external dependencies are correctly vendored or accessible through the Go module system.
gotcha Duplicate 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.
Fix: Ensure that global variables defined in your C code that are accessed by Go are marked with `extern`.
gotcha Repeated builds can be slow due to Go's default GOPATH management.
Fix: Set the `SETUPTOOLS_GOLANG_GOPATH` environment variable to reuse a consistent GOPATH, e.g., `$ SETUPTOOLS_GOLANG_GOPATH=~/go pip install .`

Install

pip install setuptools-golang Install via pip

Imports

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.

Quickstart

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))

view raw JSON →