Lupa: Python Wrapper around Lua and LuaJIT

2.6 verified Tue May 12 auth: no python install: verified

Lupa is a Python library that seamlessly integrates the runtimes of Lua or LuaJIT2 into CPython. It enables Python developers to embed Lua code, call Lua functions from Python, and interact with Python objects from within Lua. Key features include separate Lua runtime states, Python coroutine wrappers for Lua coroutines, and robust iteration support between the two languages. Currently at version 2.6, Lupa is actively maintained, with releases focusing on cross-version compatibility and feature enhancements.

pip install lupa

Common errors

error ModuleNotFoundError: No module named 'lupa' ↓

cause This error occurs when the `lupa` package or its underlying C extension modules are not correctly installed or Python cannot find them in its search path. It can also happen if you try to import `lupa` from within its source directory before it has been properly installed.

fix

Ensure lupa is installed by running pip install lupa. If you are developing and running from the source directory, install it via python setup.py install or ensure you are running your script from a directory *outside* the lupa source folder. If Cython is missing, install it first: pip install cython.

error lupa.lua54.LuaError: error loading module '...' from file '...': dynamic libraries not enabled; check your Lua installation. ↓

cause This error indicates that the Lua runtime embedded by Lupa is configured to prevent loading dynamic C modules (e.g., `.so` or `.dll` files), which is often a security measure or a build-time configuration.

fix

To enable dynamic library loading, you need to set the appropriate dlopen flags for CPython before importing lupa. Add import sys, os; sys.setdlopenflags(os.RTLD_NOW | os.RTLD_GLOBAL) before import lupa. Some environments or lupa versions might attempt to set this automatically.

error lupa._lupa.LuaError: Failed to initialise Lua runtime ↓

cause This error typically means that Lupa could not properly initialize the Lua or LuaJIT runtime. This is often due to missing shared libraries (like `libluajit-5.1.so` or `lua51.dll`), an incompatible LuaJIT/Lua version, or incorrect build configuration preventing Lupa from linking with the Lua runtime.

fix

Verify that LuaJIT or Lua (the version Lupa was built against) is correctly installed and its shared libraries are discoverable by your system's linker (e.g., in LD_LIBRARY_PATH on Linux). Reinstalling lupa after ensuring LuaJIT/Lua development files are present might resolve the issue. If building manually, ensure the LuaJIT or Lua source is in the correct directory relative to lupa's setup.py during compilation.

error error loading code: [string "<python>"]:1: unexpected symbol near 'for' ↓

cause This specific Lua error occurs when you try to execute Lua *statements* (like a `for` loop, variable assignments, or function definitions) using the `lua.eval()` method. The `eval()` method expects a Lua *expression* that returns a single value.

fix

Use the lua.execute() method for executing Lua statements or blocks of code. lua.execute() is designed to run arbitrary Lua code that doesn't necessarily return a value, or that may define functions or manipulate the Lua environment.

import lupa
lua = lupa.LuaRuntime()
lua.execute("""for i=1,4 do print(i) end""")

Warnings

breaking In Lupa 2.0, Lua stack traces within Python exception messages were reversed to align with Python's stack trace order. If you relied on the previous ordering, your error parsing logic may break. ↓

fix Adjust any code that parses Lua stack traces from Lupa's Python exceptions to account for the reversed order.

gotcha The behavior of Lua's `#` (length) operator, and thus Lupa's `len()` for wrapped Lua tables, can be unpredictable for tables containing `nil` values ('holes') or primarily acting as mappings. It generally stops at the first `nil` element, making it unsuitable for non-sequence tables. It's best not to rely on `len()` for mappings in Lupa. ↓

fix Avoid using `len()` on Lua tables from Python if they are not strict sequences without `nil` values. Instead, iterate over the table if possible, or ensure Lua-side logic handles table lengths carefully.

gotcha When passing Python objects to Lua, Lupa employs a heuristic for indexing: if the Python object has a `__getitem__` method, it's preferred for Lua's `obj[x]` and `obj.x` operations. Otherwise, attribute access is used. This can lead to unexpected behavior if an object has both attributes and `__getitem__` and you expect a specific access method from Lua. ↓

fix Be mindful of Python object structure when interacting from Lua. If precise control is needed, you might need to wrap Python objects in Lua with explicit accessors or ensure `__getitem__` is implemented (or not) as desired.

gotcha Prior to Lupa 2.1, recursive mapping of complex Python data structures (like nested lists/dicts) to Lua tables was not straightforward. Since Lupa 2.1, explicit `recursive=True` is needed in conversion functions (e.g., `LuaRuntime.table_from`) to enable deep conversion. ↓

fix For recursive data structure conversion, ensure you are using Lupa 2.1 or newer and explicitly pass `recursive=True` to the appropriate conversion methods.

gotcha Importing Lua binary modules (C modules) within a Lupa runtime typically requires CPython to enable global symbol visibility for shared libraries by calling `sys.setdlopenflags`. Lupa attempts to set these flags automatically, but it might fail on some platforms or configurations, leading to module import errors in Lua. ↓

fix If experiencing issues with Lua binary modules, check your system's `dlopen` flags and ensure they are compatible. You might need to manually configure `sys.setdlopenflags` before importing `lupa` if the automatic setup is insufficient. Consult platform-specific documentation for `dlfcn` for correct flag values.

Install

pip install lupa --global-option="--with-luajit"

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.02s 23.0M

3.10 alpine (musl) - - 0.02s 23.0M

3.10 alpine (musl) build_error - - - -

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.7s 0.00s 23M

3.10 slim (glibc) - - 0.00s 23M

3.10 slim (glibc) build_error - 11.0s - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - 0.03s 24.9M

3.11 alpine (musl) - - 0.04s 24.9M

3.11 alpine (musl) build_error - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.7s 0.00s 25M

3.11 slim (glibc) - - 0.00s 25M

3.11 slim (glibc) build_error - 10.6s - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - 0.03s 16.7M

3.12 alpine (musl) - - 0.04s 16.7M

3.12 alpine (musl) build_error - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.6s 0.00s 17M

3.12 slim (glibc) - - 0.00s 17M

3.12 slim (glibc) build_error - 12.5s - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - 0.04s 16.4M

3.13 alpine (musl) - - 0.04s 16.3M

3.13 alpine (musl) build_error - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.6s 0.00s 17M

3.13 slim (glibc) - - 0.00s 17M

3.13 slim (glibc) build_error - 1.1s - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - 0.01s 22.5M

3.9 alpine (musl) - - 0.02s 22.5M

3.9 alpine (musl) build_error - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 2.0s 0.00s 23M

3.9 slim (glibc) - - 0.00s 23M

3.9 slim (glibc) build_error - 12.7s - -

3.9 slim (glibc) - - - -

Imports

LuaRuntime
```
from lupa import LuaRuntime
```
lupa
```
import lupa
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates basic interoperability: creating a Lua runtime, evaluating Lua code, defining and calling Lua functions from Python, and exposing Python functions and builtins to the Lua environment.

import os
from lupa import LuaRuntime

# Create a Lua runtime instance
lua = LuaRuntime(unpack_returned_tuples=True)

# Evaluate Lua code directly
result_eval = lua.eval('1 + 2')
print(f'Lua eval("1 + 2"): {result_eval}')

# Define a Lua function and call it from Python
lua_add_func = lua.eval('function(x, y) return x + y end')
result_lua_call = lua_add_func(5, 7)
print(f'Called Lua function (5, 7): {result_lua_call}')

# Pass a Python function into Lua and call it
def py_multiply(a, b):
    return a * b

lua.globals().py_multiply = py_multiply
result_python_call_from_lua = lua.eval('py_multiply(3, 4)')
print(f'Called Python function from Lua (3, 4): {result_python_call_from_lua}')

# Access Python builtins from Lua
python_str_from_lua = lua.eval('python.builtins.str(123)')
print(f'Python str from Lua: {python_str_from_lua}')