Installation

LuaScript ships as a single self-contained luascript binary: the compiler, the VM, every native module, the REPL and all the tooling. You can download a prebuilt release, install it with the Go toolchain, or build it from source.

Prebuilt binaries

Every tagged release on the GitHub releases page carries archives for five platforms:

Each archive holds the binary (named after the archive, for example luascript-linux-amd64 or luascript-windows-amd64.exe) together with LICENSE and README.md. A matching .sha256 file sits next to each archive so you can verify the download.

# Linux example
sha256sum -c luascript-linux-amd64.sha256   # optional: verify the archive
tar xzf luascript-linux-amd64.tar.gz
mv luascript-linux-amd64 ~/.local/bin/luascript

Rename the binary to luascript (or luascript.exe on Windows) and put it somewhere on your PATH.

Prerequisites for building

To build or install from source you need Go 1.27 or newer (the version declared in go.mod). Nothing else is required for the default build: no C compiler and no system libraries. The db module's SQLite driver is the pure-Go modernc.org/sqlite, so the standard build is cgo-free and cross-compiles cleanly.

If your installed Go is older, go build tells you so. With the default GOTOOLCHAIN=auto setting, Go downloads the required toolchain automatically.

Install with go install

go install github.com/hilthontt/luascript/v3/cmd/luascript@latest

This builds the latest release and places luascript in $GOBIN (by default $HOME/go/bin, or %USERPROFILE%\go\bin on Windows). Make sure that directory is on your PATH. To try unreleased changes, use @main instead of @latest.

Note the module path, github.com/hilthontt/luascript/v3. It is lowercase, unlike the repository's display name HilthonTT/LuaScript, and it ends in /v3, the major-version suffix Go requires for 3.x releases.

Build from source

git clone https://github.com/HilthonTT/LuaScript
cd LuaScript
go build -o luascript ./cmd/luascript

The result is a luascript binary (add .exe on Windows) in the repository root. You can also run the interpreter straight from the source tree without building:

go run ./cmd/luascript                          # start the REPL
go run ./cmd/luascript examples/01_basics.lsc   # run a script

Makefile targets

A Makefile wraps the common workflows. It is a thin layer over go, so every target has a plain go equivalent.

See Contributing for the test, coverage, fuzz and benchmark targets.

Profile-guided builds

scripts/build-pgo.sh does a three-step PGO build: it builds the interpreter, runs luascript profile against a workload to collect a CPU profile, and rebuilds with go build -pgo=.... It needs bash.

scripts/build-pgo.sh                     # profiles examples/02_functions.lsc
scripts/build-pgo.sh path/to/script.lsc  # profiles your own workload

Optional build tags

Two build tags switch in cgo-backed implementations. Both require CGO_ENABLED=1 and a working C toolchain.

CGO_ENABLED=1 go build -tags luascript_ui -o luascript ./cmd/luascript

The plugin module, which loads Go packages at run time, needs no tag but only works in a cgo build on Linux, macOS or FreeBSD. It cannot run on Windows at all; there require("plugin") resolves but reports supported = false. Use WSL if you need it on a Windows machine.

Verify the installation

luascript -v

Version: 3.0.0, GitCommit: eb7f827, BuildTime: 2026-10-11T20:53:58Z

Release binaries carry the commit and build time they were made from. A go build from a git checkout reports the checkout's commit and commit time instead (with -dirty if the tree has uncommitted changes), and builds without that information print unknown.

Then run a one-line script:

print("Hello, LuaScript!")

luascript hello.lsc

Hello, LuaScript!

Running luascript with no arguments opens the REPL. luascript -h lists every flag and subcommand.

Editor support: VS Code

The repository includes a VS Code extension in client/. It is a thin client: it launches luascript lsp and forwards Language Server Protocol traffic over stdio. The server provides diagnostics, hover, completion, document symbols and formatting for .lsc files, and the extension adds a TextMate grammar for syntax highlighting.

The extension is built from source with Bun:

cd client
bun install            # install client dependencies (once)
bun run build:server   # go build -> ./bin/luascript.exe
bun run compile        # compile the TypeScript client to ./out

To try it, open the client/ folder in VS Code and press F5 (the "Run Extension" launch configuration). An Extension Development Host opens; open any .lsc file to activate the extension.

To produce an installable package:

bun x @vscode/vsce package

This writes a .vsix file you can install with Extensions: Install from VSIX... in VS Code. The vscode:prepublish step rebuilds the server binary and compiles the client first.

Using your own luascript binary

By default the extension starts the server binary bundled in its bin/ directory. To point it at another executable, for example one installed with go install, set the luascript.server.path setting to the absolute path of that binary.

See CLI & tooling for more on the language server.