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. |
|
Built-in codecs for utf-8, ascii, and latin-1 (iso-8859-1).
|
Built-in codecs for utf-8, ascii, and latin-1 (iso-8859-1). |
|
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 getopt is the gopy port of cpython/Python/getopt.c.
|
Package getopt is the gopy port of cpython/Python/getopt.c. |
|
Package hamt is the gopy port of cpython/Python/hamt.c.
|
Package hamt is the gopy port of cpython/Python/hamt.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 hashtable is the gopy port of cpython/Python/hashtable.c.
|
Package hashtable is the gopy port of cpython/Python/hashtable.c. |
|
init_importlib sequence.
|
init_importlib sequence. |
|
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. |
|
TYPE_CODE encoder/decoder.
|
TYPE_CODE encoder/decoder. |
|
module
|
|
|
_abc
Package abcmod is the gopy port of CPython's _abc builtin module (Modules/_abc.c).
|
Package abcmod is the gopy port of CPython's _abc builtin module (Modules/_abc.c). |
|
_codecs
Package _codecs is the gopy port of CPython's _codecs built-in module.
|
Package _codecs is the gopy port of CPython's _codecs built-in module. |
|
_csv
Package _csv is the gopy port of CPython's _csv built-in module.
|
Package _csv is the gopy port of CPython's _csv built-in module. |
|
_posixsubprocess
Package posixsubprocess is the gopy port of CPython's Modules/_posixsubprocess.c.
|
Package posixsubprocess is the gopy port of CPython's Modules/_posixsubprocess.c. |
|
_sre
Package _sre is the gopy port of CPython's _sre C extension.
|
Package _sre is the gopy port of CPython's _sre C extension. |
|
_warnings
Package _warnings is the gopy port of CPython's _warnings C accelerator.
|
Package _warnings is the gopy port of CPython's _warnings C accelerator. |
|
_weakref
Package weakrefmod is the gopy port of CPython's _weakref builtin module (Modules/_weakref.c).
|
Package weakrefmod is the gopy port of CPython's _weakref builtin module (Modules/_weakref.c). |
|
argparse
argparse: redirected to stdlib/argparse.py.
|
argparse: redirected to stdlib/argparse.py. |
|
collections
Package collections was a Go-backed shim for the collections module.
|
Package collections was a Go-backed shim for the collections module. |
|
errno
Package errno is the gopy port of CPython's built-in errno module.
|
Package errno is the gopy port of CPython's built-in errno module. |
|
functools
functools: redirected to stdlib/functools.py.
|
functools: redirected to stdlib/functools.py. |
|
gc
Package gc ports cpython/Python/gc.c.
|
Package gc ports cpython/Python/gc.c. |
|
math
Package math is a full 1:1 port of CPython's mathmodule.c.
|
Package math is a full 1:1 port of CPython's mathmodule.c. |
|
re
Package re was the Go-backed shim for the Python re module.
|
Package re was the Go-backed shim for the Python re module. |
|
socket
socket: redirected to stdlib/socket.py.
|
socket: redirected to stdlib/socket.py. |
|
sys
Inittab registration for the sys module.
|
Inittab registration for the sys module. |
|
traceback
Package traceback was a Go-backed shim for the traceback module.
|
Package traceback was a Go-backed shim for the traceback module. |
|
weakref
weakref: redirected to stdlib/weakref.py + stdlib/_weakrefset.py.
|
weakref: redirected to stdlib/weakref.py + stdlib/_weakrefset.py. |
|
Package objects ports the gating subset of cpython/Objects/.
|
Package objects ports the gating subset of cpython/Objects/. |
|
Package optimizer hosts the Tier-2 trace optimizer and uop interpreter.
|
Package optimizer hosts the Tier-2 trace optimizer and uop interpreter. |
|
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 specialize ports cpython/Python/specialize.c.
|
Package specialize ports cpython/Python/specialize.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 stdlibinit is the gopy equivalent of CPython's Modules/config.c.in.
|
Package stdlibinit is the gopy equivalent of CPython's Modules/config.c.in. |
|
Package symtable ports CPython's Python/symtable.c into Go.
|
Package symtable ports CPython's Python/symtable.c into Go. |
|
test
|
|
|
gate
Package gate runs a Python script through both CPython 3.14 and the gopy binary and compares their stdout / stderr / exit code.
|
Package gate runs a Python script through both CPython 3.14 and the gopy binary and compares their stdout / stderr / exit code. |
|
regrtest
Package regrtest is the gopy port of CPython's test driver (Lib/test/regrtest.py).
|
Package regrtest is the gopy port of CPython's test driver (Lib/test/regrtest.py). |
|
Package token declares the token kind constants shared by the lexer and tokenize packages.
|
Package token declares the token kind constants shared by the lexer and tokenize packages. |
|
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 token/types_gen.go from CPython 3.14 source.
|
Command tokens_go generates token/types_gen.go from CPython 3.14 source. |
|
uops_gen
command
Analyzer for parsed bytecode definitions: classifies uops, computes properties, escape analysis, opcode assignment.
|
Analyzer for parsed bytecode definitions: classifies uops, computes properties, escape analysis, opcode assignment. |
|
Package traceback ports cpython/Python/traceback.c.
|
Package traceback ports cpython/Python/traceback.c. |
|
__build_class__ is the builtin every `class C(...): ...` statement invokes through LOAD_BUILD_CLASS.
|
__build_class__ is the builtin every `class C(...): ...` statement invokes through LOAD_BUILD_CLASS. |
|
Package warnings is the gopy port of cpython/Python/_warnings.c.
|
Package warnings is the gopy port of cpython/Python/_warnings.c. |
|
Package weakref ports the pure-Python weak collection classes from CPython's Lib/weakref.py and Lib/_weakrefset.py: WeakSet, WeakValueDictionary, and WeakKeyDictionary.
|
Package weakref ports the pure-Python weak collection classes from CPython's Lib/weakref.py and Lib/_weakrefset.py: WeakSet, WeakValueDictionary, and WeakKeyDictionary. |
Click to show internal directories.
Click to hide internal directories.