Skip to content
goccyPublic

About

CPython in pure Go — embed and run Python anywhere Go runs. No cgo, no native Python install, one static binary.

Resources

Stars

32 stars

Watchers

0 watching

Forks

Repository files navigation

go-python

CI Go Reference

CPython in pure Go — embed and run Python anywhere Go runs. No cgo, no native Python install, one static binary.

go-python runs CPython compiled to WebAssembly and transpiled to Go by goccy/pythonwasm2go. It gives Go programs a real CPython runtime with an embedded standard library, without cgo, without a native Python installation, and without shipping a wasm runtime at execution time.

The package is built for embedding Python safely. A host application can create isolated interpreters, decide exactly what each interpreter can see or touch, call Python from Go and Go from Python with typed values and live object handles, and run agent-generated Python with explicit controls over filesystem, environment, stdio, networking, subprocesses, memory, and cancellation.

Why this library

gpython is a pure-Go Python VM, but it is a partial reimplementation / port of Python 3.4 and does not include many CPython C-backed modules. That is useful for some embedding use cases, but it is not the same thing as running CPython.

go-python takes a different path: CPython is built to WebAssembly, then the wasm is transpiled into ordinary Go source. The result keeps the deployment advantages of a Go dependency while running the CPython runtime and a bundled CPython standard library.

This matters most when Python code is produced or selected by an AI agent. The host process can execute familiar Python while still enforcing a Go-side policy before the guest reaches host resources.

Features

  • Pure Go, no cgo, no wasm runtime. CPython is compiled to WebAssembly and then transpiled to Go by goccy/pythonwasm2go. Applications import a Go module and build with the Go toolchain.
  • Real CPython with an embedded standard library. fs/stdlib.zip contains a trimmed CPython Lib/ tree and is embedded in the module. A zero-value Config serves it from a private in-memory filesystem, so a library embedding never touches the host disk.
  • A typed Go <-> Python bridge. Values cross the boundary typed, following Python's own data model: immutable built-ins by value, every other object as an identity-preserving handle. Call Python functions and methods from Go with positional and keyword arguments; expose Go functions to Python as ordinary builtin functions. Nothing is stringified in transit.
  • Auto-generated end-to-end. The generated bridge (internal/python.go) and embedded standard library (fs/stdlib.zip) are pulled from goccy/python-wasm. Updating the upstream release refreshes the generated CPython binding without hand-writing the runtime surface.
  • End-to-end provenance. Upstream-sourced artifacts are protected by GitHub artifact attestations. make verify checks the signed release provenance for both the bridge and fs/stdlib.zip, and CI runs the same verification before tests.
  • Isolated multi-instance API. Each Python owns its own wasm module, linear memory, WASI host, and CPython runtime. Instances run concurrently with independent globals and filesystem state.
  • Sandboxed by default. The zero Config denies every capability; each one is granted explicitly:
    • filesystem backends with FS — a private in-memory MemFS (the default), fs.NewHostFS(), fs.DirFS(dir), or your own;
    • guest environment variables with Env (host os.Environ is not leaked);
    • guest stdin, stdout, and stderr with explicit io.Reader / io.Writer values;
    • hostname resolution with Resolve;
    • outbound connect destinations with Dial;
    • host subprocess execution with Exec;
    • wasm linear-memory growth with MaxMemoryBytes;
    • long-running Python code with context cancellation.
  • Python command front-end. cmd/python and package cli provide a Python-like command entry point for python -c <command> and python <file.py> [args...].
  • WASI-friendly build. Because this is pure Go, embedding applications can also cross-compile to GOOS=wasip1 GOARCH=wasm. See docs/wasip1.md.

Status

The checked-in upstream artifacts currently track goccy/python-wasm v0.3.0 (vendored as goccy/pythonwasm2go v0.4.0), which builds CPython 3.14.6 with the wasmify v0.6.17 toolchain.

The main API supports expression / statement evaluation with persistent __main__ globals per instance, running script files, standard-library imports, stdout/stderr capture, typed values and live object handles in both directions, Go functions callable from Python, isolated instances, in-memory filesystems, filesystem/network/subprocess policy hooks, memory caps, and context cancellation.

The command front-end currently supports -c and script-file execution. Interactive REPL mode and python -m are not implemented yet.

Installation

go get github.com/goccy/go-python

go-python requires Go 1.25 or newer.

Synopsis

Evaluate Python

package main

import (
	"context"
	"fmt"

	python "github.com/goccy/go-python"
)

func main() {
	p, err := python.New(python.Config{})
	if err != nil {
		panic(err)
	}
	defer p.Close()

	res, err := p.Eval(context.Background(), `
import json, math
print(json.dumps({"sqrt2": round(math.sqrt(2), 6)}))
`)
	if err != nil {
		panic(err) // a host/transport failure, not a Python exception
	}
	if res.Error != nil {
		panic(res.Error) // *python.PythonError: the uncaught exception
	}
	fmt.Print(res.Stdout)
}

Result.Value is the value of the source's last expression statement (the REPL's "value of the last line"), Result.Error an uncaught exception as a *PythonError (type, message, traceback, and the live exception instance), Result.Stdout / Result.Stderr what the code printed.

Calling between Go and Python

p, _ := python.New(python.Config{})
defer p.Close()
ctx := context.Background()

// Go -> Python: define a function, fetch it as a first-class value, call it.
// Arguments and results are typed Values; Kwarg passes keyword arguments.
p.Eval(ctx, "def add(a, b=0):\n    return a + b")
r, _ := p.Eval(ctx, "add")
add, _ := python.As[python.FunctionValue](r.Value)
sum, _ := add.Call(ctx, python.ValueOf(40), python.Kwarg("b", python.ValueOf(2)))
n, _ := python.As[python.IntValue](sum)
v, _ := n.Int64()
fmt.Println(v) // 42

// Python objects cross as handles, not copies: the same object, its methods,
// and its state remain live on the Go side.
p.Eval(ctx, "class Counter:\n    def __init__(self): self.n = 0\n    def inc(self): self.n += 1\nc = Counter()")
r, _ = p.Eval(ctx, "c")
obj, _ := python.As[python.ObjectValue](r.Value) // TypeName() == "__main__.Counter"
obj.CallMethod(ctx, "inc")                       // mutates the object Python sees
again, _ := p.Eval(ctx, "c")
fmt.Println(obj.Equal(again.Value.(python.ObjectValue))) // true: same object

// Modules and containers are typed handles too.
js, _ := p.Import(ctx, "json")
d, _ := p.NewDict(ctx, python.DictItem{Key: python.ValueOf("a"), Value: python.ValueOf(1)})
s, _ := js.CallMethod(ctx, "dumps", d, python.Kwarg("sort_keys", python.ValueOf(true)))
fmt.Println(s.(python.StrValue).String()) // {"a": 1}

// Python -> Go: expose a Go function as a Python builtin function.
p.Bind("go_upper", func(args []python.Value, kwargs map[string]python.Value) (python.Value, error) {
	s, err := python.As[python.StrValue](args[0])
	if err != nil {
		return nil, err
	}
	return python.ValueOf(strings.ToUpper(s.String())), nil
})
r, _ = p.Eval(ctx, `go_upper("hello")`)
fmt.Println(r.Value.(python.StrValue).String()) // HELLO

Every value crosses the boundary typed, following Python's own data model. A Value is one of the sealed concrete types: NoneValue, BoolValue, IntValue (arbitrary precision — Int64() or BigInt()), FloatValue, ComplexValue, StrValue, BytesValue cross by value; ListValue, TupleValue, DictValue, SetValue, FrozenSetValue, FunctionValue, ClassValue, ModuleValue, and every other object (an instance, an exception, a generator, ...) cross as identity-preserving handles that all implement the ObjectValue interface — Python's object protocol: Attr / SetAttr, Item / SetItem / DelItem, Len, Contains, Call / CallMethod, Str / Repr, IsInstance. Inspect a value with a Go type switch (concrete cases first, ObjectValue last) or with python.As[T] when the expected type is known; Kind() reports the runtime kind.

Only exact instances of the immutable built-ins cross by value: an IntEnum member or a str subclass instance keeps its identity and attributes and arrives as an object handle. Container subclasses get the container's typed handle (an OrderedDict is a DictValue whose TypeName() says collections.OrderedDict). Handles hold the object alive in the interpreter until the Go value is garbage collected or the instance is closed. A Go function receives its arguments the same way, returns one Value (nil is None), and raises in Python by returning an error: a *PythonError re-raises that exact exception instance, any other error becomes a RuntimeError.

Run agent-generated code in a tighter sandbox

The zero-value Config is already a deny-all sandbox: a private in-memory filesystem pre-loaded with the standard library, an empty environment, no host stdio, and no networking or subprocess access. Grant only what the code needs:

p, err := python.New(python.Config{
	Env:            []string{"APP_MODE=agent"},
	MaxMemoryBytes: 64 << 20,
	Resolve:        func(host string) bool { return host == "api.example.com" },
	Dial: func(network, host, ip string, port int) bool {
		return host == "api.example.com" && port == 443
	},
})
if err != nil {
	panic(err)
}
defer p.Close()

res, err := p.Eval(context.Background(), "sum(range(101))")
if err != nil {
	panic(err)
}
if res.Error != nil {
	panic(res.Error)
}
n, _ := python.As[python.IntValue](res.Value)
fmt.Println(n.BigInt()) // 5050

To give the interpreter files of your own, build the filesystem first: fs.NewStdlibMemFS() returns the default in-memory filesystem to add to, and the fs package provides fs.NewHostFS() (the host filesystem, how the python command runs) and fs.DirFS(dir) (the host filesystem scoped to one directory). With a host backend, point StdlibDir at the directory fs.ExtractStdlib() returns.

Interrupt a long-running evaluation

Cancel the context. The interpreter is stopped at the next bytecode boundary by a host-side memory write (CPython's own eval-breaker mechanism, no wasm code executed on the busy instance) and the call returns ctx.Err().

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
_, err := p.Eval(ctx, "while True:\n    pass")
fmt.Println(errors.Is(err, context.DeadlineExceeded)) // true; p stays usable

Run a script file

err := p.RunFile(ctx, "/app/main.py", []string{"arg1"}) // as __main__, sys.argv set
if code, ok := python.ExitCode(err); ok {
	os.Exit(code) // the script called sys.exit()
}

RunFile streams output to Config.Stdout / Config.Stderr rather than capturing it, and AddPath prepends directories to sys.path.

Use the command front-end

go run ./cmd/python -c 'import sys; print(sys.version)'
go run ./cmd/python ./script.py arg1 arg2

Verifying provenance

The generated bridge and embedded standard library are release artifacts from goccy/python-wasm. You can verify that the local files came from the trusted upstream release workflow without a GitHub access token:

make verify

The target:

  1. computes the SHA-256 digest of internal/python.go and fs/stdlib.zip;
  2. fetches the public attestation bundle for each digest from the GitHub attestations API;
  3. runs gh attestation verify --bundle with --signer-workflow goccy/python-wasm/.github/workflows/release.yml.

CI runs make verify before go test ./..., so pull requests must preserve the signed upstream artifacts.

Resource footprint

The runtime cost is different from a small hand-written interpreter. This package embeds a CPython standard library archive and depends on a wasm2go-transpiled CPython engine, so cold builds and interpreter startup are heavier than a typical Go dependency. In exchange, applications get a cgo-free, cross-compilable CPython runtime whose host access is mediated through Go.

For local measurements, run:

go test ./...
cd bench
go test -bench . -benchmem ./...
go test -run TestMemoryFootprint -v ./...

The bench/ module runs identical Python source on go-python (real CPython 3.14.6, python-wasm v0.3.0) and on gpython (a pure-Go Python 3.4 VM), so the two are measured on equal footing (benchstat sec/op, n=10, Go darwin/amd64 on an Apple M5):

workload go-python gpython
fib(28) (recursive calls) 47.1 ms 204.0 ms
sum(range(200000)) (loop) 17.3 ms 16.7 ms
interpreter startup (New + Close) 10.5 ms 12.6 µs

The two make different trade-offs: go-python runs a real CPython engine, so it is faster on call-heavy code and keeps per-call allocation tiny (96 B and 5 allocations per fib(28) run, against gpython's 440 MiB and 5.1 M allocations), and its tight loops now run at parity; gpython's lightweight VM starts up in microseconds. Startup here is the zero Config: the in-memory standard library is inflated once per process and each instance is populated from that cache, then CPython boots. One live instance holds about 52 MiB of Go heap (the wasm linear memory plus its private stdlib filesystem).

License

  • The Go source code of this repository is licensed under MIT. That covers everything written or generated here — the public API, the generated bridge internal/python.go, the CLI, the tests and the benchmarks.
  • fs/stdlib.zip is not MIT: it is a repackaged subset of the CPython 3.14.6 standard library — a derivative work of CPython — and keeps CPython's own license, the Python Software Foundation License Agreement (LICENSE-PSF), vendored verbatim. CPython is Copyright (c) 2001-present Python Software Foundation; All Rights Reserved.
  • The pythonwasm2go dependency (the transpiled interpreter) is likewise distributed under CPython's license in its own repository.

Using go-python in your own project

  • As a library dependency (source distribution): your repository contains no CPython-derived bytes — only an import path and a go.mod entry. License your own code however you like (MIT, proprietary, ...); no CPython license text needs to accompany it. Your users receive go-python and pythonwasm2go from their own origins, under their own licenses.
  • Shipping a compiled binary: the binary embeds the transpiled interpreter and fs/stdlib.zip. The PSF License Agreement is permissive and expressly allows this — it grants the right to "reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python ... in any derivative version" (§2), including in commercial and closed-source products, with no copyleft. Your own code keeps its own license and does not inherit CPython's. The only condition is attribution: retain CPython's copyright notice and PSF's license — shipping LICENSE-PSF (or a third-party-notices entry pointing at it) alongside your binary satisfies it. So redistribution, including inside a proprietary product, is fine.
  • Python code you run on the interpreter, and its output, remain yours.

This summary is not legal advice; the license texts govern.

About

CPython in pure Go — embed and run Python anywhere Go runs. No cgo, no native Python install, one static binary.

Resources

Stars

32 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages