README
¶
gopy
gopy is a from-scratch Go reimplementation of the CPython interpreter
core. The goal is 100% behavioural compatibility with upstream CPython
3.14: same data structures, same models, same wire formats, same error
messages. The only thing that changes is the surface API style, which
adopts Go idioms modelled on the Go standard library.
Status: very early. v0.0.x is project scaffolding. The interpreter does not run Python code yet. The roadmap is tracked in the project notes and surfaced through the changelog.
Non-goals
- No alternative semantics. If gopy diverges from CPython, the bug is in gopy.
- No CPython C extension ABI.
.soand.pydmodules are out of scope. Native modules are reimplemented in Go on demand. - No Python 2.
Install
Requires Go 1.26 or newer.
go install github.com/tamnd/gopy/cmd/gopy@latest
Or grab a prebuilt binary from the releases page.
Quick start
$ gopy --version
gopy 0.1.0 (3.14.0+) [go1.26 darwin/arm64]
$ gopy --copyright
Copyright (c) 2026 The gopy Authors. All Rights Reserved.
...
Build from source
git clone https://github.com/tamnd/gopy
cd gopy
make build
./bin/gopy --version
Common developer tasks live in the Makefile:
| Target | What it does |
|---|---|
make build |
Build the gopy binary into ./bin/gopy |
make test |
Run the unit tests with the race detector |
make cover |
Produce coverage.txt and print total coverage |
make vet |
Run go vet |
make lint |
Run golangci-lint (must be installed locally) |
make tidy |
Run go mod tidy |
Repository layout
gopy/
build/ version, platform, compiler, copyright strings
cmd/gopy/ interpreter entry point (mirrors CPython python.c)
changelog/ per-release changelog fragments
.github/ workflows, dependabot, code owners, templates
The runtime packages live at the module root (no internal/) so that
embedders and companion modules can import them directly.
Contributing
Patches are welcome. Please read CONTRIBUTING.md and the Code of Conduct before opening a pull request.
Security issues should follow the disclosure procedure in SECURITY.md.
License
gopy is distributed under the Apache License, Version 2.0. See
LICENSE for the full text.
Portions of the design and observable behavior are derived from CPython, which is distributed under the Python Software Foundation License.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package abstract ports the gating subset of cpython/Objects/abstract.c.
|
Package abstract ports the gating subset of cpython/Objects/abstract.c. |
|
Package arena is a bump allocator with a linked list of fixed-size blocks.
|
Package arena is a bump allocator with a linked list of fixed-size blocks. |
|
Package brc ports cpython/Python/brc.c.
|
Package brc ports cpython/Python/brc.c. |
|
Package build holds the static version, platform, compiler, and copyright strings reported by the gopy runtime.
|
Package build holds the static version, platform, compiler, and copyright strings reported by the gopy runtime. |
|
cmd
|
|
|
gopy
command
Command gopy is the gopy interpreter entry point.
|
Command gopy is the gopy interpreter entry point. |
|
Package errors ports cpython/Python/errors.c and the gating subset of cpython/Objects/exceptions.c.
|
Package errors ports cpython/Python/errors.c and the gating subset of cpython/Objects/exceptions.c. |
|
Package format ports cpython/Python/formatter_unicode.c.
|
Package format ports cpython/Python/formatter_unicode.c. |
|
Package gc ports the refcount-only path of cpython/Python/gc.c.
|
Package gc ports the refcount-only path of cpython/Python/gc.c. |
|
Package hash holds the hashing primitives ported from cpython/Python/pyhash.c and cpython/Python/bootstrap_hash.c.
|
Package hash holds the hashing primitives ported from cpython/Python/pyhash.c and cpython/Python/bootstrap_hash.c. |
|
Package objects ports the gating subset of cpython/Objects/.
|
Package objects ports the gating subset of cpython/Objects/. |
|
Package pymath ports cpython/Python/pymath.c plus the math sentinels CPython exposes via Include/pymath.h.
|
Package pymath ports cpython/Python/pymath.c plus the math sentinels CPython exposes via Include/pymath.h. |
|
Package pystrconv ports the locale-independent string and number conversion utilities from cpython/Python/.
|
Package pystrconv ports the locale-independent string and number conversion utilities from cpython/Python/. |
|
Package pysync ports the synchronization primitives in cpython/Python/lock.c, parking_lot.c, and critical_section.c.
|
Package pysync ports the synchronization primitives in cpython/Python/lock.c, parking_lot.c, and critical_section.c. |
|
Package pythread is the cross-platform threading shim ported from cpython/Python/thread.c.
|
Package pythread is the cross-platform threading shim ported from cpython/Python/thread.c. |
|
Package state ports the skeleton of cpython/Python/pystate.c.
|
Package state ports the skeleton of cpython/Python/pystate.c. |
|
Package traceback ports cpython/Python/traceback.c.
|
Package traceback ports cpython/Python/traceback.c. |