google/starlark-go: a Starlark interpreter you embed in Go programs

The problem starlark-go solves, and for whom

Starlark is a dialect of Python intended to be used as a configuration language. The README is explicit that a Starlark interpreter is typically embedded within a larger application, and that the host application may define additional domain-specific functions and data types beyond the core language. That sentence is the whole design brief. You are not being handed a general-purpose scripting runtime; you are being handed a small, readable notation that you can expose to people who configure or extend your program.

The audience follows from that. If you maintain a Go application and you have caught yourself writing a bespoke expression parser, or shipping YAML plus a pile of special-case keys, Starlark is the alternative: real functions, lexical scope, and garbage collection, in a syntax Python programmers already read. The README names the canonical example, Bazel, where Starlark is the notation for BUILD files and for the macro language that extends the build tool. That precedent matters because it shows the intended shape: many small files, evaluated by a host that supplies the domain vocabulary.

It is not a Python replacement. The README frames Starlark as a dialect, and the language definition lives in doc/spec.md rather than being inherited from CPython. Anyone arriving expecting to run existing Python code should stop here.

How the interpreter is put together

The repository layout is the clearest description of the architecture. The starlark/ directory holds the interpreter and its Go API, and it is the package you import. syntax/ handles parsing, resolve/ does name resolution, and internal/ holds machinery the project does not expose. lib/ contains the standard library, with starlarkjson/ and starlarkstruct/ as separate importable packages for JSON and struct support. cmd/ holds the command-line interpreter, repl/ the read-eval-print loop, and starlarktest/ test helpers. doc/ carries spec.md and impl.md.

Two properties from the README shape how that code behaves. First, independent Starlark threads execute in parallel, so Starlark workloads scale well on parallel machines. This is a deliberate divergence from CPython, and it is the reason a Starlark value model cannot simply be Python's. Second, the API is built around an explicit thread object. In the embedding example, a starlark.Thread is constructed with a name, then passed to ExecFile, to Call, and to whatever else needs to evaluate. Execution state is not ambient; it is a parameter.

That thread argument is more than bookkeeping. It is where a host application attaches behavior, and it is the seam between the sandboxed script and the Go program that owns the file system, the network, and the clock. The interpreter by itself does not grant those capabilities.

Installing the interpreter and running a first script

The README's getting-started section installs the command-line interpreter into $GOPATH/bin:

# check out the code and dependencies,
# and install interpreter in $GOPATH/bin
$ go install go.starlark.net/cmd/starlark@latest

After that, starlark is on your path. The README's example script, coins.star, builds a dictionary of coin names to values and prints it twice, once sorted by name and once sorted by value using the dictionary's get method as the sort key:

coins = {
  'dime': 10,
  'nickel': 5,
  'penny': 1,
  'quarter': 25,
}
print('By name:\t' + ', '.join(sorted(coins.keys())))
print('By value:\t' + ', '.join(sorted(coins.keys(), key=coins.get)))

Running starlark coins.star should print two tab-separated lines, the first listing the coins alphabetically and the second listing them from penny to quarter. If you would rather experiment interactively, running starlark with no arguments drops you into the REPL, where the README defines and calls a fibonacci function and gets back [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]. Ctrl-D closes the REPL's input stream.

For the embedding case, the import path is go.starlark.net/starlark. The README's example creates a thread, calls starlark.ExecFile with the filename and two nil arguments, reads the fibonacci global out of the returned globals map, and calls it from Go with starlark.Call, passing a starlark.Tuple containing starlark.MakeInt(10). The example_test.go file in the starlark package has more.

The stability promise is deliberately weak

The README's Stability section states that the project reserves the right to make breaking language and API changes, though it will endeavor to keep them to a minimum, and that once the Bazel team has finalized the version 1 language specification it will be more rigorous. Read that as a contract term, not a caveat. If you embed this interpreter and expose Starlark to your users, you are accepting that a future release may change the language or the Go API underneath you. The README says so plainly.

There is a second constraint in the same section. The project aims to support the most recent two go1.x releases of the Go toolchain. The README gives the pattern: if the latest release is go1.26, it supports go1.26 and go1.25 but not go1.24, mirroring the support window of the golang.org/x modules it depends on, and it calls supporting older versions impractical. go.mod pins the module to go 1.25.0. If your build is stuck on an older toolchain, this is not a project that will accommodate you.

A third boundary is procedural rather than technical. The README directs proposals to change the language itself to the Starlark site maintained by the Bazel team, not to the maintainers of this repository, and says the Go implementation may only proceed once there is consensus that a change is desirable. It also asks contributors to file or claim an issue first, and to complete Google's contributor license agreement before a first change. The Go implementation follows the Java implementation used by Bazel; the two are meant to agree.

When to reach for something else

The most direct alternative is the Java implementation of Starlark used by Bazel and maintained by the Bazel team, which the README names as the implementation the Go version strives to match. The difference is not in the language but in the host: if your application is written in Java, embedding the Java interpreter keeps you in one runtime and one build, and it is the implementation the language specification is finalized against. Choosing the Go interpreter only makes sense when the host program is Go.

If the host is Go but the requirement is a full Python runtime, the answer is a CPython embedding rather than Starlark, and the README's own framing explains why: Starlark is a small and simple language, and the interpreter deliberately does not carry Python's surface. Whether that trade is acceptable depends entirely on what you are letting users write. Configuration and small extension scripts fit. Arbitrary programs do not.

There is also the option of not embedding a language at all. If your configuration is genuinely flat, a data format plus validation code is less machinery than an interpreter, a thread object, and a global namespace to manage. Starlark earns its place when users need functions to eliminate repetition, which is the README's own justification for the language.

Licence, maintenance and what an upgrade costs

Starlark in Go is copyright (c) 2018 The Bazel Authors and provided under a 3-clause BSD license, per the README's Legal section, with the full text in LICENSE. The README also notes that it is not an official Google product. For most integrators a permissive BSD-3-Clause licence is unremarkable, but the attribution and disclaimer clauses still need to travel with any redistribution, and the CLA requirement applies to contributions you send back, not to your own use of the code. Nothing here is legal advice; read LICENSE against your own distribution model.

The repository is not archived, and the last push was on 2026-09-12. There are no releases listed, so upgrades arrive as commits on the master branch rather than as tagged versions. That combination is the practical cost: you cannot pin to a stable release line, so you either track master or vendor a specific commit and review changes yourself. The go.mod file gives the dependency surface you inherit, which includes github.com/chzyer/readline, github.com/google/go-cmp, golang.org/x/sys, golang.org/x/term, and google.golang.org/protobuf.

Because the README permits breaking language and API changes before the version 1 specification is finalized, budget for reading the diff when you move forward. The two documents worth checking first are doc/spec.md for the language and doc/impl.md for the Go implementation.

Editorial conclusion

Adopt google/starlark-go if you are writing a Go application and want user-supplied configuration or scripting evaluated in a language with Python-like syntax and parallel threads, and you can absorb the breaking changes the README says are still permitted. Do not adopt it if you need a frozen language specification, a Python-compatible runtime, or a supported toolchain older than the most recent two Go releases. Before committing, read doc/spec.md for the language definition and doc/impl.md for the Go implementation's behavior, then run the interpreter against one of your own configuration files rather than the coins.star example.

Frequently asked questions

Official sources

1. google/starlark-go on GitHub
2. Issues
3. License: BSD-3-Clause
4. README