Codectionary / Developer documentation / Lua

Choose a verified Lua installer for your operating system, try the interactive interpreter, configure VS Code, and understand LuaRocks packages.

Choose Lua for the place you will run it

For standalone learning, install a maintained Lua release and use its matching manual. If you plan to script a game or another host, check which Lua version that host embeds: system Lua may have different syntax or libraries. Install from the official Lua site, a distribution package, or a trusted package manager; do not assume Lua comes with VS Code.

After installation, open a new terminal and check the version. Some distributions expose a versioned command such as lua5.4 rather than plain lua. Use that same command in the examples if needed.

Check the interpreter

lua -v

Windows installation

The Lua starting page links to LuaBinaries for ready-made Windows builds. Choose the build matching your processor and intended Lua version, download it from the project linked there, extract it to a folder you control, and make the folder containing lua.exe available on PATH if you want to run it from any terminal. Reopen PowerShell after changing PATH, then run lua -v.

If PowerShell says lua is not recognised, try running lua.exe directly from its extracted folder first. That separates an installation problem from a PATH problem. Check the archive’s publisher and filename before extracting; LuaBinaries is a project linked by Lua’s site, not the Lua source distribution itself.

Verify in a new PowerShell window

lua -v

macOS installation

On macOS, a maintained package manager can install the standalone interpreter. If you already use Homebrew, brew install lua installs its current Lua formula. Open a new Terminal window and run lua -v. If the command is still missing, check Homebrew’s own PATH setup for your machine; Apple Silicon and Intel Macs can have different Homebrew prefixes.

Homebrew is optional. The Lua starting page also explains building from the official source. Avoid replacing or modifying system-managed tools just to follow this guide.

Homebrew setup

brew install lua
lua -v

Linux installation

Linux commands depend on the distribution. On Ubuntu or Debian, install the versioned lua5.4 package from the distribution repository, then run lua5.4 -v. On Fedora, install the lua package with dnf and check lua -v. Distribution packages may be older than the current upstream release; use the manual that matches the installed version.

If a command is missing after installation, check the package name and whether your distribution uses a versioned executable. You do not need a web server or LuaRocks to run a basic .lua file.

Ubuntu or Debian

sudo apt update
sudo apt install lua5.4
lua5.4 -v

Fedora

sudo dnf install lua
lua -v

Experiment in the interactive interpreter

Type lua with no filename to start its interactive prompt, also called a REPL: read a line, evaluate it, print any expression result, repeat. Try = 2 + 3 to see a result, then print("Hi") to see output produced by print. The expression result and print output are related but not the same thing. Type os.exit() to leave, or use your terminal’s end-of-input shortcut.

The REPL is useful for checking a small expression. Save longer programs in .lua files so you can rerun and edit them. Some hosts ship a different interactive environment or none at all.

Start interactive Lua

lua

At the Lua prompt

= 2 + 3
print("Hi")
os.exit()

Edit Lua in VS Code

Install Visual Studio Code from its official site, open a folder for your Lua work, and create hello.lua. VS Code is an editor, not a Lua runtime: install Lua separately and use the integrated terminal to run lua hello.lua. Syntax highlighting is available through language support; the Lua Language Server extension can add completion and diagnostics when you need them.

If code runs in an external terminal but not VS Code’s integrated terminal, restart VS Code after changing PATH and compare the interpreter command in both terminals. A language extension cannot fix a missing interpreter.

Run the saved file in VS Code’s terminal

lua hello.lua

Add libraries with LuaRocks

LuaRocks is a package manager for Lua libraries. First install LuaRocks using its official instructions or a maintained package for your operating system; it is separate from Lua. Run luarocks --version to confirm it is present, then luarocks list to see installed rocks. A rock is a packaged library. Use packages only when your program needs them and check the package’s source, maintenance and supported Lua versions.

For a small practice project, dkjson is a Lua JSON library available through LuaRocks. Install it for the Lua version your project uses, then require("dkjson") in a Lua file. If the module is not found, inspect the LuaRocks installation path and version with luarocks config and confirm you are running the same Lua interpreter; do not solve routine package problems by changing system permissions globally.

Inspect LuaRocks and install a small library

luarocks --version
luarocks list
luarocks install dkjson

Move from setup to a program

The interpreter is ready when its version command works. Create a .lua file, run it from the folder where you saved it, and read any error in the terminal. Learn the core language before relying on host-specific APIs or external libraries.

Syntax

lua -v
lua hello.lua

Examples

Test a Lua expression

Start lua, then enter these lines at the prompt.

= 2 + 3
print("Hi")
  1. The first line asks the interactive interpreter to display the expression result, 5.
  2. The second line calls print, which writes Hi as program output. Use this quick loop to try syntax before putting it in a file.

Use a library installed with LuaRocks

After installing dkjson for this Lua interpreter, save as json-example.lua and run it locally.

local json = require("dkjson")
local result = json.encode({name = "Ada"})
print(result) -- {"name":"Ada"}
  1. require loads the dkjson module from the interpreter’s module search path. The table has one named field, so its JSON object has one property.
  2. json.encode converts the Lua table to JSON text and print writes that text to the terminal. If require fails, check that LuaRocks installed the library for the Lua version you are running.

Best practices

  • Verify the installed interpreter version and use its matching documentation.
  • Keep editor setup and language runtime setup separate.
  • Check package compatibility and source before adding a rock.

Runtime & versions

Lua interpreter or a host application. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

Lua reference manuals

Specifications & further reading