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.
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.
- 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.zipcontains a trimmed CPythonLib/tree and is embedded in the module. A zero-valueConfigserves 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 fromgoccy/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 verifychecks the signed release provenance for both the bridge andfs/stdlib.zip, and CI runs the same verification before tests. - Isolated multi-instance API. Each
Pythonowns 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
Configdenies every capability; each one is granted explicitly:- filesystem backends with
FS— a private in-memoryMemFS(the default),fs.NewHostFS(),fs.DirFS(dir), or your own; - guest environment variables with
Env(hostos.Environis not leaked); - guest
stdin,stdout, andstderrwith explicitio.Reader/io.Writervalues; - 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
contextcancellation.
- filesystem backends with
- Python command front-end.
cmd/pythonand packagecliprovide a Python-like command entry point forpython -c <command>andpython <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.
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.
go get github.com/goccy/go-pythongo-python requires Go 1.25 or newer.
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.
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()) // HELLOEvery 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.
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()) // 5050To 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.
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 usableerr := 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.
go run ./cmd/python -c 'import sys; print(sys.version)'
go run ./cmd/python ./script.py arg1 arg2The 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 verifyThe target:
- computes the SHA-256 digest of
internal/python.goandfs/stdlib.zip; - fetches the public attestation bundle for each digest from the GitHub attestations API;
- runs
gh attestation verify --bundlewith--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.
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).
- 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.zipis 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
pythonwasm2godependency (the transpiled interpreter) is likewise distributed under CPython's license in its own repository.
- 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 — shippingLICENSE-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.