Yaegi Documentation

Use the provided installation script for CI environments. You can specify the target binary directory using the -b flag.

curl -sfL https://raw.githubusercontent.com/traefik/yaegi/master/install.sh | bash -s -- -b $GOPATH/bin v0.9.0

You can bridge compiled Go code with interpreted code by evaluating a script and then retrieving symbols as reflect.Value objects. Use the Interface() method and type assertion to convert these values into usable Go functions or types.

package main

import "github.com/traefik/yaegi/interp"

const src = `package foo
func Bar(s string) string { return s + "-Foo" }`

func main() {
	i := interp.New(interp.Options{})

	_, err := i.Eval(src)
	if err != nil {
		panic(err)
	}

	v, err := i.Eval("foo.Bar")
	if err != nil {
		panic(err)
	}

	bar := v.Interface().(func(string) string)

	r := bar("Kung")
	println(r)
}

The yaegi binary provides an interactive REPL. In interactive mode, all standard library packages are pre-imported and available for direct use. You can also run specific Go packages, directories, or files directly from the CLI.

# Start interactive REPL
$ yaegi
> import "fmt"
> fmt.Println("Hello World")
Hello World

# Run a specific package with syscall and unsafe support
$ yaegi -syscall -unsafe -unrestricted github.com/traefik/yaegi/cmd/yaegi

# Use as a shebang for Go scripting
#!/usr/bin/env yaegi
package main
import "fmt"
func main() { fmt.Println("test") }

To embed Yaegi, create a new interpreter using interp.New(), provide configuration via interp.Options{}, and load required symbols (such as the standard library) using i.Use(). Execute Go code strings using i.Eval().

package main

import (
	"github.com/traefik/yaegi/interp"
	"github.com/traefik/yaegi/stdlib"
)

func main() {
	i := interp.New(interp.Options{})

	i.Use(stdlib.Symbols)

	_, err := i.Eval(`import "fmt"`)
	if err != nil {
		panic(err)
	}

	_, err = i.Eval(`fmt.Println("Hello Yaegi")`)
	if err != nil {
		panic(err)
	}
}

You can install the yaegi CLI tool using go install. For an improved interactive experience with command history and editing, it is recommended to use rlwrap and alias the command.

go install github.com/traefik/yaegi/cmd/yaegi@latest

# Recommended: use rlwrap for history and editing
alias yaegi='rlwrap yaegi'

To use Yaegi as an embedded interpreter in your Go applications, import the interp package.

import "github.com/traefik/yaegi/interp"

Be aware of the following unsupported features and limitations:

• Assembly: .s files are not supported.
• C Interop: Calling C code is not supported.
• Compiler Directives: Directives for the compiler, linker, or embedding files are not supported.
• Dynamic Interfaces: Interfaces used from pre-compiled code cannot be added dynamically (requires pre-compiled interface wrappers).
• Reflection/Printing: reflect type representation and %T printing may differ between compiled and interpreted modes.
• Performance: Computationally intensive code is significantly slower in interpreted mode.
• Go Modules: Go modules are not yet supported; source must be installed into $GOPATH/src for testing.

When using the yaegi test command, you can control which symbol sets are included by setting the following environment variables. This is useful for configuring the interpreter behavior in CI or shell environments without passing flags explicitly.

• YAEGI_SYSCALL: Set to true to include syscall symbols.
• YAEGI_UNRESTRICTED: Set to true to include unrestricted symbols.
• YAEGI_UNSAFE: Set to true to include unsafe symbols.

Use the following flags to modify the behavior of the yaegi interpreter during execution:

The following commands are available in the yaegi executable: