Managing Packages with LuaRocks

March 12, 2026 · 4 min read ·Updated April 6, 2026 ·beginner

luarockspackagespackage-managerdependenciesrocksstdlib

Lua ships with a small standard library. For everything else — HTTPS networking, JSON parsing, filesystem access, markdown processing — there is LuaRocks. It is the package manager for Lua: a command-line tool that queries the central repository at luarocks.org and installs self-contained packages called rocks onto your system or into a local directory.

If you have used pip (Python), Bundler (Ruby), or npm (Node), LuaRocks will feel immediately familiar.

Installing LuaRocks

On Linux, your package manager probably has it:

# Debian/Ubuntu
sudo apt install luarocks

# Fedora/RHEL
sudo dnf install lua-rocks

On macOS, install with Homebrew or compile from source:

brew install luarocks

On Windows, follow the instructions on the LuaRocks wiki.

To verify it installed correctly:

luarocks --version

Finding Packages

Before installing, search the repository:

luarocks search luafilesystem

Search results:
==============
Rockspecs and source rocks:
---------------------------
luafilesystem
   1.8.0-1 (rockspec) - https://luarocks.org
   1.8.0-1 (src) - https://luarocks.org
   1.7.0-1 (rockspec) - https://luarocks.org
   ...

The search lists available versions and whether they are rockspecs (source descriptions that get compiled at install time) or pre-built rock archives.

Installing Packages

The default install is system-wide, which requires write access to wherever LuaRocks is configured (often /usr/local):

luarocks install luafilesystem

For a local install — which is what you want in most development scenarios — use --local:

luarocks install --local luafilesystem

Local installs go to ~/.luarocks. This keeps your user directory tidy and does not require root or admin privileges.

Project-Local Trees

For individual projects, you can install into a custom directory:

mkdir myproject/vendor
luarocks install --tree=myproject/vendor luatex

The --tree option creates an isolated vendor directory for that project’s dependencies. When you run your Lua code, add that tree to package.path:

package.path = package.path .. ";myproject/vendor/share/lua/5.4/?.lua"
package.cpath = package.cpath .. ";myproject/vendor/lib/lua/5.4/?.so"

local lfs = require("lfs")  -- now finds lfs from your project tree

This pattern is the LuaRocks equivalent of a node_modules directory.

Listing Installed Packages

See everything you have installed:

luarocks list

Installed rocks:
----------------
luafilesystem
   1.8.0-1 (installed) - /home/user/.luarocks/lib/luarocks/rocks
luasocket
   3.1.0-1 (installed) - /home/user/.luarocks/lib/luarocks/rocks
luasec
   1.3.0-1 (installed) - /home/user/.luarocks/lib/luarocks/rocks

Listing shows the version, install location, and whether each rock is current or has newer versions available.

Getting Package Information

luarocks show prints details about an installed rock:

luarocks show luafilesystem

luafilesystem 1.8.0-1
-------------------------
LuaFileSystem is a Lua library developed to complement the
and filesystem functions.
License: MIT
Homepage: https://github.com/lunarmodules/luafilesystem
Installed in: /home/user/.luarocks

This tells you what the package does, its license, the project homepage, and where it is installed.

Removing Packages

To uninstall a locally installed rock:

luarocks remove --local luasec

To remove everything installed in the current tree:

luarocks purge

Be careful with purge — it wipes all rocks from that tree, not just one.

Requiring Installed Modules

Once installed, require works as normal:

local socket = require("socket")
local https = require("ssl.https")
local lfs = require("lfs")

LuaRocks configures the module search paths automatically. You do not need to manually adjust package.path unless you are using a project-local tree with --tree.

To see what paths LuaRocks is currently using:

luarocks path

This prints LUA_PATH and LUA_CPATH values you can source or paste into your shell profile.

Configuring the Lua Version

If you have multiple Lua versions installed, specify which one to use:

luarocks install --lua-version=5.4 luafilesystem

Or set a default:

luarocks config --lua-version 5.4

This is useful when working on projects that require a specific Lua version. For example, a legacy codebase on Lua 5.1 can coexist on the same machine alongside a newer project using Lua 5.4 — just prefix your commands with --lua-version=5.1 or set the config globally per project directory.

Publishing Your Own Package

To share a library on LuaRocks, create a rockspec file — mylib-1.0-1.rockspec:

package = "mylib"
version = "1.0-1"
source = {
  url = "git://github.com/username/mylib"
}
dependencies = {
  "lua >= 5.1",
  "luafilesystem"
}
build = {
  type = "builtin",
  modules = {
    mylib = "src/mylib.lua"
  }
}

Then upload it:

luarocks upload mylib-1.0-1.rockspec

You need an account at luarocks.org. After uploading, your package appears in the search index.

Common Packages to Know

Package	What it does
`luafilesystem`	Filesystem operations (lfs)
`luasocket`	TCP/UDP networking
`luasec`	HTTPS support via OpenSSL
`dkjson`	JSON encoding/decoding
`lua-cjson`	Fast JSON (C library)
`penlight`	Utility library
`moonscript`	Compile-to-Lua language
`tl`	Teal typed Lua
`markdown`	Markdown to HTML