Run a file

gopy takes the same shape of invocation as python3: pass a filename, pass -c "code", pass -m module, or pipe a script on stdin. The exit status follows POSIX and CPython conventions.

A filename

gopy hello.py

gopy reads the file, runs compile.Compile to produce a Code object, and hands that code object to pythonrun.Run. The module runs as __main__. sys.argv[0] is the filename, and sys.argv[1:] holds any additional arguments.

gopy hello.py one two three
# inside the script: sys.argv == ["hello.py", "one", "two", "three"]

A one-liner with -c

gopy -c 'print(2 ** 10)'

The string passed to -c is compiled with mode="single". That mode is the same one CPython's REPL uses; it allows expression statements to print their value implicitly.

A module with -m

gopy -m http.server 8000

-m is parsed but not yet wired in gopy. The intended behaviour matches CPython: import the module from sys.path and run it as __main__. Until the flag lands, pass the source path directly.

Stdin

echo 'print("hi from stdin")' | gopy

When stdin is not a TTY and no filename is given, gopy reads stdin to EOF and treats the contents as a script.

Exit codes

Value	Meaning
0	The interpreter terminated cleanly.
1	An unhandled exception escaped the top frame.
2	A bad command-line argument or a missing file.
n	sys.exit(n) exited with code n.
130	The interpreter was interrupted by SIGINT.

These numeric codes are the ones CPython documents in Modules/main.c. gopy emits them from cmd/gopy/main.go.

How long it takes

A trivial script like the one in the hello-world page completes in a few milliseconds. Most of that is the process start. Once the interpreter is up, parsing and compiling add a few hundred microseconds for short modules; the eval loop itself is where the performance gap with CPython lives.

For latency-sensitive work, embed the interpreter once and reuse a compiled Code object across calls. Starting a fresh gopy process on every request pays start-up cost you can amortise.

What gopy reads from disk

Path	Read when
The script file	Always.
Imported .py files	On import name.
Imported .pyc files	On import name, if a cache is found.
$GOPY_STDLIB directory	At startup, to seed sys.path.
$PYTHONPATH directories	At startup, prepended to sys.path.

gopy does not read the system Python install. It does not pick up /usr/lib/python3.14/, virtualenvs, conda environments, or site-packages. To make a third-party .py module available to gopy, place it on PYTHONPATH or co-locate it with your script.