Lua's Hidden Startup Hook

Caspian — Sun, 19 Jul 2026 09:50:44 +0000

While reading through the Lua source code, I stumbled upon a small but interesting feature that I had never noticed before: LUA_INIT.

Lua has a built-in startup initialization mechanism that allows you to execute Lua code automatically whenever the standalone interpreter starts.

It is controlled through an environment variable LUA_INIT

By setting this variable, you can make Lua run a piece of code before executing your actual script.

Running initialization code directly

The simplest form is putting Lua code directly into LUA_INIT.

For example:

export LUA_INIT='print("Lua is starting!")'

Now when you run:

lua myscript.lua

Lua will first execute:

print("Lua is starting!")

and then continue running myscript.lua.

This can be useful for setting global variables, configuring your environment, loading helper modules, or debugging.

Loading an initialization file

Instead of embedding code in an environment variable, you can prefix the value with @ and provide a filename:

export LUA_INIT='@startup.lua'

Now Lua will load and execute:

startup.lua

before running your program.

This is a much cleaner approach for larger initialization logic.

For example:

-- startup.lua

package.path = package.path .. ";./modules/?.lua"

DEBUG = true

print("Custom Lua environment loaded")

Every Lua session started with that environment variable will automatically use this configuration.

Setting LUA_INIT temporarily in PowerShell

While experimenting with this feature, I also learned a useful PowerShell trick.

Unlike Unix shells where you might do:

LUA_INIT='print("hello")' lua script.lua

PowerShell uses a different syntax for environment variables.

You can create a temporary environment variable for a command using:

powershell -Command { $env:LUA_INIT = "print('hello from init')"; lua.exe script.lua }

The variable only exists inside that PowerShell command scope and is passed to lua.exe.

This is a convenient way to test LUA_INIT without permanently modifying your system environment.

Looking at the source code

While exploring the Lua standalone interpreter source (lua.c), this behavior can be found in the initialization handling code.

The interpreter checks:

LUA_INIT_ with the Lua version suffix for example:

LUA_INIT_5_5='print("Hello")' lua

will also work.

LUA_INIT as a fallback

Then it decides whether the value is code or a file.

Conceptually:

if (init starts with '@')
    load and execute the file
else
    execute the string as Lua code

The implementation is small, but it provides a powerful extension point.

A small detail: "before anything else" is not literally everything

The initialization code runs very early, but it is not the very first thing Lua does.

Before calling the LUA_INIT handler, the standalone interpreter has already:

created the Lua state
initialized the standard libraries
parsed command-line arguments
performed some interpreter setup
started garbage collection

Only after these steps does Lua execute the initialization chunk.

So LUA_INIT is better described as:

"Run custom Lua code before executing the user's script or interactive session."

rather than:

"Run code before Lua starts."

Why is this useful?

There are many practical uses:

Development helpers

Automatically enable debugging:

export LUA_INIT='debug = true'

Custom environments

Load frequently used modules:

require("my_helpers")

Local tooling

Create project-specific Lua startup behavior:

export LUA_INIT='@.lua_startup.lua'

Experimenting with Lua internals

For people reading Lua's source code, LUA_INIT is also a nice example of how the standalone interpreter connects the operating system environment with the Lua runtime.

Final thoughts

LUA_INIT is a tiny feature hidden inside Lua's interpreter, but it demonstrates one of Lua's strengths: the runtime stays simple while still providing powerful extension points.

Sometimes reading source code reveals features that are not obvious from everyday usage — and LUA_INIT is one of those small gems.

DEV Community: Caspian