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 ast holds the Python AST data model.
|
Package ast holds the Python AST data model. |
|
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 compile holds the AST-to-bytecode pipeline.
|
Package compile holds the AST-to-bytecode pipeline. |
|
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 future ports cpython/Python/future.c.
|
Package future ports cpython/Python/future.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 initconfig ports cpython/Python/preconfig.c and cpython/Python/initconfig.c.
|
Package initconfig ports cpython/Python/preconfig.c and cpython/Python/initconfig.c. |
|
Package lifecycle ports the cpython/Python/pylifecycle.c boot sequence: pre-init, core init, main init, finalize.
|
Package lifecycle ports the cpython/Python/pylifecycle.c boot sequence: pre-init, core init, main init, finalize. |
|
Package marshal is the Go port of cpython/Python/marshal.c.
|
Package marshal is the Go port of cpython/Python/marshal.c. |
|
Package objects ports the gating subset of cpython/Objects/.
|
Package objects ports the gating subset of cpython/Objects/. |
|
Package parser is the top-level entry point: source bytes in, ast.Mod out.
|
Package parser is the top-level entry point: source bytes in, ast.Mod out. |
|
errors
Package errors holds the SyntaxError text panel and the helpers that turn (parser, token, message) into a structured *SyntaxError.
|
Package errors holds the SyntaxError text panel and the helpers that turn (parser, token, message) into a structured *SyntaxError. |
|
lexer
Package lexer ports cpython/Parser/lexer/ and cpython/Parser/tokenizer/ to Go.
|
Package lexer ports cpython/Parser/lexer/ and cpython/Parser/tokenizer/ to Go. |
|
pegen
Package pegen ports the runtime half of cpython 3.14 Parser/pegen.c and pegen.h.
|
Package pegen ports the runtime half of cpython 3.14 Parser/pegen.c and pegen.h. |
|
string
Package string ports cpython/Parser/string_parser.c.
|
Package string ports cpython/Parser/string_parser.c. |
|
Package pathconfig is the gopy port of cpython/Modules/getpath.py (the resolved logic, not the script itself).
|
Package pathconfig is the gopy port of cpython/Modules/getpath.py (the resolved logic, not the script itself). |
|
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 pythonrun ports cpython/Python/pythonrun.c.
|
Package pythonrun ports cpython/Python/pythonrun.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 stackref is the tagged stack-value representation the bytecode interpreter operates on.
|
Package stackref is the tagged stack-value representation the bytecode interpreter operates on. |
|
Package state ports the skeleton of cpython/Python/pystate.c.
|
Package state ports the skeleton of cpython/Python/pystate.c. |
|
Package symtable ports CPython's Python/symtable.c into Go.
|
Package symtable ports CPython's Python/symtable.c into Go. |
|
Package sys ports cpython/Python/sysmodule.c.
|
Package sys ports cpython/Python/sysmodule.c. |
|
Package tokenize is the Go port of cpython/Python/Python-tokenize.c.
|
Package tokenize is the Go port of cpython/Python/Python-tokenize.c. |
|
tools
|
|
|
asdl_go
command
Command asdl_go generates ast/nodes_gen.go from cpython/Parser/Python.asdl.
|
Command asdl_go generates ast/nodes_gen.go from cpython/Parser/Python.asdl. |
|
bytecodes_gen
command
|
|
|
opcodes_go
command
Command opcodes_go generates compile/opcodes_gen.go from CPython 3.14 source.
|
Command opcodes_go generates compile/opcodes_gen.go from CPython 3.14 source. |
|
parser_gen
command
Command parser_gen generates the PEG parser table for gopy from cpython/Grammar/python.gram.
|
Command parser_gen generates the PEG parser table for gopy from cpython/Grammar/python.gram. |
|
tokens_go
command
Command tokens_go generates tokenize/types_gen.go from CPython 3.14 source.
|
Command tokens_go generates tokenize/types_gen.go from CPython 3.14 source. |
|
Package traceback ports cpython/Python/traceback.c.
|
Package traceback ports cpython/Python/traceback.c. |
|
Wires objects.FunctionType.Call so a Python-defined function can be invoked through objects.Call.
|
Wires objects.FunctionType.Call so a Python-defined function can be invoked through objects.Call. |
|
Package warnings is the gopy port of cpython/Python/_warnings.c.
|
Package warnings is the gopy port of cpython/Python/_warnings.c. |
Click to show internal directories.
Click to hide internal directories.