Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 32 ยท Errors, Modules and Coroutines

Modules and require

Learn how Lua modules work: returning a table from a file, require and package.loaded caching, package.path, avoiding globals and using _ENV for sandboxes.

A program that lives in one file stops being pleasant long before it gets big. Lua's answer to splitting code up is wonderfully small: a module is just a file that returns a value, usually a table of functions, and require loads it once and hands you that value. There is no special module syntax to learn.

In this lesson you will write modules with the module-as-table pattern, see exactly what require does and why a module is only loaded once, learn how package.path finds files, and meet _ENV, the hidden table behind every global variable. It helps to know tables and functions first.

Lua is not installed on this site, so the file-based examples are read-only: they need several files on disk. The runnable examples are JavaScript stand-ins that model require, the module cache and _ENV.

A module is a file that returns a value

One file The chunk runs top to bottom.
A table Public functions are fields of it.
return M The last line hands it to require.
1 / 2

The module-as-table pattern

Suppose a file called stack.lua contains this:

LUA
local Stack = {}

local function newItems()
  return {}
end

function Stack.new()
  return {items = newItems(), size = 0}
end

function Stack.push(s, value)
  s.size = s.size + 1
  s.items[s.size] = value
end

function Stack.pop(s)
  if s.size == 0 then
    return nil
  end
  local value = s.items[s.size]
  s.items[s.size] = nil
  s.size = s.size - 1
  return value
end

return Stack

Three ideas make this a good module. The table Stack is declared local, so it does not leak into the global namespace. Helper functions such as newItems are local too, which makes them private: nothing outside the file can call them. And the file ends with return Stack, which is the value require gives back.

Another file uses it like this:

LUA
local Stack = require("stack")

local s = Stack.new()
Stack.push(s, "a")
Stack.push(s, "b")
print(Stack.pop(s), Stack.pop(s), Stack.pop(s))
TEXT
b	a	nil

Note that the string passed to require has no .lua extension. You choose the local name freely (local Stack, local stack, local S); it is only a variable.

What require does

When you call require("stack"), Lua works through these steps:

  1. It looks in the table package.loaded for a key "stack". If a value is there, require returns it at once and does nothing else.
  2. Otherwise it asks each function in package.searchers to find a loader. The usual searchers check package.preload, then look for a Lua file through package.path, then for a C library through package.cpath.
  3. It calls the loader with the module name (and, in Lua 5.4, the path it found) as arguments.
  4. If the module returned a value other than nil, that value is stored in package.loaded["stack"]. If it returned nothing and nothing else was stored, Lua stores true.
  5. require returns the value (and, in Lua 5.4, a second result: the loader data, usually the file path).

If no searcher finds the module, require raises an error that lists every file name it tried, which is a very useful hint when a path is wrong.

Why a module loads only once

Because step 1 checks the cache, the module file runs a single time per program, no matter how many files require it. Every file that asks for "stack" receives the same table. That makes modules natural singletons, and it means state stored at the top of a module (a counter, a configuration table) is shared by all users.

JS A model of require and package.loaded

Press Run (or Ctrl + Enter) to see the console output here.

No output.

package.path and finding files

package.path is a string of templates separated by semicolons. In each template a ? stands for the module name, with every dot in the name replaced by the directory separator. So require("util.strings") with the template ./?.lua looks for ./util/strings.lua.

LUA
print(package.path)

The default value depends on how Lua was built and on the LUA_PATH environment variable, so the output differs between machines. Most standard builds start with templates like ./?.lua, which means "the current directory". To add your own folder, put it at the front of the string before you call require:

LUA
package.path = "./lib/?.lua;./lib/?/init.lua;" .. package.path

local json = require("json")          -- finds ./lib/json.lua
local strings = require("util.strings") -- finds ./lib/util/strings.lua

The second template, ?/init.lua, lets a folder act as a module: require("util") loads ./lib/util/init.lua if no util.lua exists. Note that the search path is relative to where you start the program, not to the file that calls require. Running lua src/main.lua from the project root and from inside src can therefore behave differently.

package.preload["name"] lets you register a loader function directly, which is handy for testing and for programs that bundle everything into one file.

Avoiding globals

Lua variables are global by default: forgetting local creates a global that every file can read and overwrite. In a module that is a bug waiting to happen.

LUA
-- bad: leaks `helper` and `count` into every other file
count = 0
function helper() count = count + 1 end

-- good: private by default, public on purpose
local count = 0
local function helper() count = count + 1 end

Old Lua 5.1 code used a module(...) function to declare modules. It was removed in Lua 5.2, and the table pattern above replaced it. If you read an old tutorial that uses module, translate it to local M = {} ... return M.

Circular requires deserve a warning. If a.lua requires b.lua and b.lua requires a.lua, the cache entry for the first one does not exist yet while it is loading, so the two keep calling each other until the stack overflows. Break the cycle by moving shared code into a third module, or by calling require inside a function instead of at the top of the file.

_ENV: where globals really live

Here is the secret: a global name like print is just shorthand for _ENV.print. Every chunk has an upvalue called _ENV, which normally refers to the table _G that holds the standard library. When you write x = 5 with no local x in scope, Lua reads it as _ENV.x = 5.

Because _ENV is an ordinary variable, you can declare your own and change what every global name inside the scope means:

LUA
local print = print        -- keep a private copy first
local _ENV = {}            -- from here on, globals go into a fresh table

x = 5                      -- really _ENV.x = 5
print(x)
print(y)
TEXT
5
nil

Only the real print we saved in a local still works; everything else in the standard library is gone, because the new _ENV is empty. This is the foundation of sandboxing: run untrusted code with an _ENV that contains only the functions you are willing to let it call. A second useful trick is a "strict" environment that turns typos into errors by giving the table a metatable (see Metatables and Metamethods):

LUA
setmetatable(_G, {
  __newindex = function(_, name)
    error("assignment to undeclared global '" .. name .. "'", 2)
  end,
  __index = function(_, name)
    error("undeclared variable '" .. name .. "'", 2)
  end,
})

After that, a misspelled variable fails loudly instead of quietly becoming nil. Install it at the start of your main file, and declare intentional globals with rawset(_G, "name", value).

JS Strict globals and a sandbox

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Putting it together

A tidy project often looks like this:

TEXT
project/
  main.lua
  lib/
    json.lua
    util/
      strings.lua
      init.lua

main.lua sets package.path once, then requires what it needs. Each module returns a table, keeps helpers local, and requires its own dependencies at the top. Because everything is explicit, you can see at a glance what a file depends on. For loading code from strings or arbitrary files rather than modules, Lua also offers load, loadfile and dofile, but require is the right tool for normal program structure.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a Lua module file usually end with?

    A module is a chunk that returns a value, normally a table. require stores and returns that value.
  2. 2. You call require("stack") twice in different files. How many times does stack.lua run?

    require first looks in package.loaded. After the first load the result is stored there, so every later call returns the same value.
  3. 3. With the template ./?.lua, which file does require("util.strings") look for?

    The ? is replaced by the module name with each dot turned into a directory separator.
  4. 4. What is x = 5 shorthand for when no local x is in scope?

    Free names are fields of the table in the _ENV upvalue, which normally is _G.
  5. 5. Why should module helpers be declared with local?

    A local function is invisible outside its file, so it cannot clash with other code. Globals are shared by every file.

Summary

  • A module is a file that returns a value, usually a table of functions.
  • Keep helpers and state local; expose only what belongs to the public table.
  • require(name) checks package.loaded, searches package.path, runs the file once and caches the result.
  • Dots in module names become directory separators; extend package.path to add folders.
  • Avoid circular requires; move shared code to a third module.
  • Globals are fields of _ENV; a custom _ENV creates sandboxes, and a metatable on _G catches typos.

Continue with Coroutines.