Command line interface

gopy [options] [-c cmd | -m mod | file | -] [arg ...]

The argument parser lives in getopt/getopt.go and follows CPython's Modules/main.c and Modules/getpath.c. gopy parses the full CPython short-option set; not all of them have effect yet. This page is honest about which is which.

Wired flags

These flags work today.

Option	Effect
`-c cmd`	Run `cmd` as a single statement; remaining args become `sys.argv`.
`file`	Execute `file` as `__main__`. `sys.argv[0]` is the filename.
`-`	Read the program from stdin (also the default when stdin is not a TTY).
`-V`, `--version`	Print version and exit.
`-h`, `--help`, `-?`	Print usage and exit.
(no args)	Enter the interactive REPL.

Parsed but not yet wired

These flags are accepted (you will not get a parse error) but have no effect yet. They are listed here so you can recognise gaps when you compare against CPython.

Option	What it should do (per CPython)
`-m mod`	Import `mod` and run it as `__main__`.
`-i`	Drop into the REPL after the script.
`-q`	Suppress the REPL banner.
`-u`	Force unbuffered stdout/stderr.
`-v`	Verbose import tracing.
`-O`, `-OO`	Optimise; strip assertions / docstrings.
`-S`	Skip implicit `import site`.
`-E`	Ignore `PYTHON*` environment variables.
`-I`	Isolated mode (`-E -s -P` combined).
`-s`	Don't add the user site directory to `sys.path`.
`-P`	Don't prepend script directory to `sys.path`.
`-b`, `-bb`	Warn / error on `bytes`/`str` mixing.
`-B`	Don't write `.pyc` files.
`-d`	Debug mode (CPython prints parser debug; gopy treats this as a no-op).
`-R`	Already-default hash randomisation (kept for compatibility).
`-t`	Removed in CPython 3; accepted for back-compat.
`-W arg`	Add a warning filter.
`-X opt`	Set an implementation option in `sys._xoptions`.
`-x`	Skip the first source line (shebang in scripts started by other interpreters).

The wiring lands one section at a time as the underlying subsystems mature. See Status for the current state.

Environment variables

gopy reads two environment variables at startup today:

Variable	Effect
`PYTHONPATH`	Prepended to `sys.path`. Colon-separated on POSIX, semicolon on Windows.
`GOPY_STDLIB`	Override the directory gopy walks for bundled `.py` resources.

The full CPython environment surface (PYTHONHOME, PYTHONSTARTUP, PYTHONHASHSEED, PYTHONOPTIMIZE, PYTHONUNBUFFERED, PYTHONUTF8, ...) is not yet honoured; the plumbing arrives with initconfig.c port.

Exit codes

Code	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 follow Modules/main.c. Implementation is in cmd/gopy/main.go.

Examples

Run a script with arguments:

gopy script.py --flag value
# inside the script: sys.argv == ["script.py", "--flag", "value"]

Evaluate an expression:

gopy -c 'import sys; print(sys.version_info)'

Pipe a script:

cat <<'PY' | gopy
import json
print(json.dumps({"hello": "gopy"}, indent=2))
PY

Run a one-liner under timing:

time gopy -c 'sum(i*i for i in range(1_000_000))'

Compatibility checklist

When porting a CPython invocation, the failure modes you may hit today are:

-m some.module is silently ignored; pass a path instead.
-O does not strip asserts. Don't rely on __debug__ == False.
PYTHONPATH works; PYTHONHASHSEED and the rest do not.
python -X dev does nothing (no sys._xoptions plumbing yet).

For anything that does not fit, file an issue on the tracker with the invocation and the expected behaviour.

Wired flags​

Parsed but not yet wired​

Environment variables​

Exit codes​

Examples​

Compatibility checklist​

See also​