Building with LuaJIT2

1. Download and unpack lupa

   http://pypi.python.org/pypi/lupa

2. Download LuaJIT2

   http://luajit.org/download.html

3. Unpack the archive into the lupa base directory, e.g.:

   .../lupa-0.1/LuaJIT-2.0.2

4. Build LuaJIT:

   cd LuaJIT-2.0.2
   make
   cd ..

   If you need specific C compiler flags, pass them to make as follows:

   make CFLAGS="..."

   For trickier target platforms like Windows and MacOS-X, please see the official installation instructions for LuaJIT.

   NOTE: When building on Windows, make sure that lua51.lib is made in addition to lua51.dll. The MSVC build produces this file, MinGW does NOT.

5. Build lupa:

   python setup.py build_ext -i

   Or any other distutils target of your choice, such as build or one of the bdist targets. See the distutils documentation for help, also the hints on building extension modules.

   Note that on 64bit MacOS-X installations, the following additional compiler flags are reportedly required due to the embedded LuaJIT:

   -pagezero_size 10000 -image_base 100000000

   You can find additional installation hints for MacOS-X in this somewhat unclear blog post, which may or may not tell you at which point in the installation process to provide these flags.

   Also, on 64bit MacOS-X, you will typically have to set the environment variable ARCHFLAGS to make sure it only builds for your system instead of trying to generate a fat binary with both 32bit and 64bit support:

   export ARCHFLAGS="-arch x86_64"

   Note that this applies to both LuaJIT and Lupa, so make sure you try a clean build of everything if you forgot to set it initially.

Starting with Lupa 2.7, abi3 wheels can be built by passing the setup.py option --limited-api or by setting the environment variable LUPA_LIMITED_API.

Examples are:

# build for the ABI version of the currently running Python
python3.11 setup.py build_wheel --limited-api=true

# build for a specific Python ABI version, e.g. Python 3.9
python3 setup.py build_wheel --limited-api=3.9

Building with Lua 5.x

It also works to use Lupa with the standard (non-JIT) Lua runtime. The easiest way is to use the bundled lua submodule:

1. Clone the respective submodule, e.g. Lua 5.4:

   $ git submodule update --init third-party/lua54

2. Build Lupa:

   $ python3 setup.py bdist_wheel --use-bundle --with-cython

You can also build it by installing a Lua 5.x package, including any development packages (header files etc.). On systems that use the “pkg-config” configuration mechanism, Lupa’s setup.py will pick up either LuaJIT2 or Lua automatically, with a preference for LuaJIT2 if it is found. Pass the --no-luajit option to the setup.py script if you have both installed but do not want to use LuaJIT2.

On other systems, you may have to supply the build parameters externally, e.g. using environment variables or by changing the setup.py script manually. Pass the --no-luajit option to the setup.py script in order to ignore the failure you get when neither LuaJIT2 nor Lua are found automatically.

For further information, read this mailing list post:

https://www.freelists.org/post/lupa-dev/Lupa-with-normal-Lua-interpreter-Lua-51,2

Debian/Ubuntu + Lua 5.2

1. Install Lua 5.2 development package:

   $ apt-get install liblua5.2-dev

2. Install lupa:

   $ pip install lupa

Debian/Ubuntu + LuaJIT2

1. Install LuaJIT2 development package:

   $ apt-get install libluajit-5.1-dev

2. Install lupa:

   $ pip install lupa

Depending on OS version, you might get an older LuaJIT2 version.

OS X + Lua 5.2 + Homebrew

1. Install Lua:

   $ brew install lua

2. Install pkg-config:

   $ brew install pkg-config

3. Install lupa:

   $ pip install lupa

2.8 (2026-04-15)

• GH#288: No changes in source or functionality, just removed files from the sdist content that prevented it from building on non-x86_64 platforms.

• Py3.8 wheels were excluded due to lack of usage. The package still builds and is tested on Py3.8, but no pre-built wheels are provided.

2.7 (2026-04-07)

• In Lua 5.5, the string hash seed can be configured for each LuaRuntime.

• The bundled LuaJIT versions were updated to the latest git branches.

• Lua 5.5 is included in the binary wheels.

• Lupa can be built as abi3 wheel.

• Some lesser used platforms are served with abi3 wheels.

• Built with Cython 3.2.4.

2.6 (2025-10-24)

• The bundled LuaJIT versions were updated to the latest git branches.

• Built with Cython 3.1.6.

2.5 (2025-06-15)

• GH#284: Lua uses dlopen() again, which was lost in Lupa 2.3. Patch by Philipp Krones.

• The bundled Lua 5.4 was updated to 5.4.8.

• The bundled LuaJIT versions were updated to the latest git branches.

• Built with Cython 3.1.2.

2.4 (2025-01-10)

• The windows wheels now bundle LuaJIT 2.0 and 2.1. (patch by Michal Plichta)

• Failures in the test suite didn’t set a non-zero process exit value.

2.3 (2025-01-09)

• The bundled LuaJIT versions were updated to the latest git branches.

• The bundled Lua 5.4 was updated to 5.4.7.

• Removed support for Python 2.x.

• Built with Cython 3.0.11.

2.2 (2024-06-02)

• A new method LuaRuntime.gccollect() was added to trigger the Lua garbage collector.

• A new context manager LuaRuntime.nogc() was added to temporarily disable the Lua garbage collector.

• Freeing Python objects from a thread while running Lua code could run into a deadlock.

• The bundled LuaJIT versions were updated to the latest git branches.

• Built with Cython 3.0.10.

2.1 (2024-03-24)

• GH#199: The table_from() method gained a new keyword argument recursive=False. If true, Python data structures will be recursively mapped to Lua tables, taking care of loops and duplicates via identity de-duplication.

• GH#248: The LuaRuntime methods “eval”, “execute” and “compile” gained new keyword options mode and name that allow constraining the input type and modifying the (chunk) name shown in error messages, following similar arguments in the Lua load() function. See https://www.lua.org/manual/5.4/manual.html#pdf-load

• GH#246: Loading Lua modules did not work for the version specific Lua modules introduced in Lupa 2.0. It turned out that it can only be enabled for one of them in a given Python run, so it is now left to users to enable it explicitly at need. (original patch by Richard Connon)

• GH#234: The bundled Lua 5.1 was updated to 5.1.5 and Lua 5.2 to 5.2.4. (patch by xxyzz)

• The bundled Lua 5.4 was updated to 5.4.6.

• The bundled LuaJIT versions were updated to the latest git branches.

• Built with Cython 3.0.9 for improved support of Python 3.12/13.

2.0 (2023-04-03)

• GH#217: Lua stack traces in Python exception messages are now reversed to match the order of Python stack traces.

• GH#196: Lupa now ships separate extension modules built with Lua 5.3, Lua 5.4, LuaJIT 2.0 and LuaJIT 2.1 beta. Note that this is build specific and may depend on the platform. A normal Python import cascade can be used.

• GH#211: A new option max_memory allows to limit the memory usage of Lua code. (patch by Leo Developer)

• GH#171: Python references in Lua are now more safely reference counted to prevent garbage collection glitches. (patch by Guilherme Dantas)

• GH#146: Lua integers in Lua 5.3+ are converted from and to Python integers. (patch by Guilherme Dantas)

• GH#180: The python.enumerate() function now returns indices as integers if supported by Lua. (patch by Guilherme Dantas)

• GH#178: The Lua integer limits can be read from the module as LUA_MAXINTEGER and LUA_MININTEGER. (patch by Guilherme Dantas)

• GH#174: Failures while calling the __index method in Lua during a table index lookup from Python could crash Python. (patch by Guilherme Dantas)

• GH#137: Passing None as a dict key into table_from() crashed. (patch by Leo Developer)

• GH#176: A new function python.args(*args, **kwargs) was added to help with building Python argument tuples and keyword argument dicts for Python function calls from Lua code.

• GH#177: Tables that are not sequences raise IndexError when unpacking them. Previously, non-sequential items were simply ignored.

• GH#179: Resolve some C compiler warnings about signed/unsigned comparisons. (patch by Guilherme Dantas)

• Built with Cython 0.29.34.

1.14.1 (2022-11-16)

• Rebuild with Cython 0.29.32 to support Python 3.11.

1.13 (2022-03-01)

• Bundled Lua source files were missing in the source distribution.

1.12 (2022-02-24)

• GH#197: Some binary wheels in the last releases were not correctly linked with Lua.

• GH#194: An absolute file path appeared in the SOURCES.txt metadata of the source distribution.

1.11 (2022-02-23)

• Use Lua 5.4.4 in binary wheels and as bundled Lua.

• Built with Cython 0.29.28 to support Python 3.10/11.

1.10 (2021-09-02)

• GH#147: Lua 5.4 is supported. (patch by Russel Davis)

• The runtime version of the Lua library as a tuple (e.g. (5,3)) is provided via lupa.LUA_VERSION and LuaRuntime.lua_version.

• The Lua implementation name and version string is provided as LuaRuntime.lua_implementation.

• setup.py accepts new command line arguments --lua-lib and --lua-includes to specify the

• Use Lua 5.4.3 in binary wheels and as bundled Lua.

• Built with Cython 0.29.24 to support Python 3.9.

1.9 (2019-12-21)

• Build against Lua 5.3 if available.

• Use Lua 5.3.5 in binary wheels and as bundled Lua.

• GH#129: Fix Lua module loading in Python 3.x.

• GH#126: Fix build on Linux systems that install Lua as “lua52” package.

• Built with Cython 0.29.14 for better Py3.8 compatibility.

1.8 (2019-02-01)

• GH#107: Fix a deprecated import in Py3.

• Built with Cython 0.29.3 for better Py3.7 compatibility.

1.7 (2018-08-06)

• GH#103: Provide wheels for MS Windows and fix MSVC build on Py2.7.

1.6 (2017-12-15)

• GH#95: Improved compatibility with Lua 5.3. (patch by TitanSnow)

1.5 (2017-09-16)

• GH#93: New method LuaRuntime.compile() to compile Lua code without executing it. (patch by TitanSnow)

• GH#91: Lua 5.3 is bundled in the source distribution to simplify one-shot installs. (patch by TitanSnow)

• GH#87: Lua stack trace is included in output in debug mode. (patch by aaiyer)

• GH#78: Allow Lua code to intercept Python exceptions. (patch by Sergey Dobrov)

• Built with Cython 0.26.1.

1.4 (2016-12-10)

• GH#82: Lua coroutines were using the wrong runtime state (patch by Sergey Dobrov)

• GH#81: copy locally provided Lua DLL into installed package on Windows (patch by Gareth Coles)

• built with Cython 0.25.2

1.3 (2016-04-12)

• GH#70: eval() and execute() accept optional positional arguments (patch by John Vandenberg)

• GH#65: calling str() on a Python object from Lua could fail if the LuaRuntime is set up without auto-encoding (patch by Mikhail Korobov)

• GH#63: attribute/keyword names were not properly encoded if the LuaRuntime is set up without auto-encoding (patch by Mikhail Korobov)

• built with Cython 0.24

1.2 (2015-10-10)

• callbacks returned from Lua coroutines were incorrectly mixing coroutine state with global Lua state (patch by Mikhail Korobov)

• availability of python.builtins in Lua can be disabled via LuaRuntime option.

• built with Cython 0.23.4

1.1 (2014-11-21)

• new module function lupa.lua_type() that returns the Lua type of a wrapped object as string, or None for normal Python objects

• new helper method LuaRuntime.table_from(...) that creates a Lua table from one or more Python mappings and/or sequences

• new lupa.unpacks_lua_table and lupa.unpacks_lua_table_method decorators to allow calling Python functions from Lua using named arguments

• fix a hang on shutdown where the LuaRuntime failed to deallocate due to reference cycles

• Lupa now plays more nicely with other Lua extensions that create userdata objects

1.0.1 (2014-10-11)

• fix a crash when requesting attributes of wrapped Lua coroutine objects

• looking up attributes on Lua objects that do not support it now always raises an AttributeError instead of sometimes raising a TypeError depending on the attribute name

1.0 (2014-09-28)

• NOTE: this release includes the major backwards incompatible changes listed below. It is believed that they simplify the interaction between Python code and Lua code by more strongly following idiomatic Lua on the Lua side.

  • Instead of passing a wrapped python.none object into Lua, None return values are now mapped to nil, making them more straight forward to handle in Lua code. This makes the behaviour more consistent, as it was previously somewhat arbitrary where none could appear and where a nil value was used. The only remaining exception is during iteration, where the first returned value must not be nil in Lua, or otherwise the loop terminates prematurely. To prevent this, any None value that the iterator returns, or any first item in exploded tuples that is None, is still mapped to python.none. Any further values returned in the same iteration will be mapped to nil if they are None, not to none. This means that only the first argument needs to be manually checked for this special case. For the enumerate() iterator, the counter is never None and thus the following unpacked items will never be mapped to python.none.

  • When unpack_returned_tuples=True, iteration now also unpacks tuple values, including enumerate() iteration, which yields a flat sequence of counter and unpacked values.

  • When calling bound Python methods from Lua as “obj:meth()”, Lupa now prevents Python from prepending the self argument a second time, so that the Python method is now called as “obj.meth()”. Previously, it was called as “obj.meth(obj)”. Note that this can be undesired when the object itself is explicitly passed as first argument from Lua, e.g. when calling “func(obj)” where “func” is “obj.meth”, but these constellations should be rare. As a work-around for this case, user code can wrap the bound method in another function so that the final call comes from Python.

• garbage collection works for reference cycles that span both runtimes, Python and Lua

• calling from Python into Lua and back into Python did not clean up the Lua call arguments before the innermost call, so that they could leak into the nested Python call or its return arguments

• support for Lua 5.2 (in addition to Lua 5.1 and LuaJIT 2.0)

• Lua tables support Python’s “del” statement for item deletion (patch by Jason Fried)

• Attribute lookup can use a more fine-grained control mechanism by implementing explicit getter and setter functions for a LuaRuntime (attribute_handlers argument). Patch by Brian Moe.

• item assignments/lookups on Lua objects from Python no longer special case double underscore names (as opposed to attribute lookups)

0.21 (2014-02-12)

• some garbage collection issues were cleaned up using new Cython features

• new LuaRuntime option unpack_returned_tuples which automatically unpacks tuples returned from Python functions into separate Lua objects (instead of returning a single Python tuple object)

• some internal wrapper classes were removed from the module API

• Windows build fixes

• Py3.x build fixes

• support for building with Lua 5.1 instead of LuaJIT (setup.py –no-luajit)

• no longer uses Cython by default when building from released sources (pass --with-cython to explicitly request a rebuild)

• requires Cython 0.20+ when building from unreleased sources

• built with Cython 0.20.1

0.20 (2011-05-22)

• fix “deallocating None” crash while iterating over Lua tables in Python code

• support for filtering attribute access to Python objects for Lua code

• fix: setting source encoding for Lua code was broken

0.19 (2011-03-06)

• fix serious resource leak when creating multiple LuaRuntime instances

• portability fix for binary module importing

0.18 (2010-11-06)

• fix iteration by returning Py_None object for None instead of nil, which would terminate the iteration

• when converting Python values to Lua, represent None as a Py_None object in places where nil has a special meaning, but leave it as nil where it doesn’t hurt

• support for counter start value in python.enumerate()

• native implementation for python.enumerate() that is several times faster

• much faster Lua iteration over Python objects

0.17 (2010-11-05)

• new helper function python.enumerate() in Lua that returns a Lua iterator for a Python object and adds the 0-based index to each item.

• new helper function python.iterex() in Lua that returns a Lua iterator for a Python object and unpacks any tuples that the iterator yields.

• new helper function python.iter() in Lua that returns a Lua iterator for a Python object.

• reestablished the python.as_function() helper function for Lua code as it can be needed in cases where Lua cannot determine how to run a Python function.

0.16 (2010-09-03)

• dropped python.as_function() helper function for Lua as all Python objects are callable from Lua now (potentially raising a TypeError at call time if they are not callable)

• fix regression in 0.13 and later where ordinary Lua functions failed to print due to an accidentally used meta table

• fix crash when calling str() on wrapped Lua objects without metatable

0.15 (2010-09-02)

• support for loading binary Lua modules on systems that support it

0.14 (2010-08-31)

• relicensed to the MIT license used by LuaJIT2 to simplify licensing considerations

0.13.1 (2010-08-30)

• fix Cython generated C file using Cython 0.13

0.13 (2010-08-29)

• fixed undefined behaviour on str(lua_object) when the object’s __tostring() meta method fails

• removed redundant “error:” prefix from LuaError messages

• access to Python’s python.builtins from Lua code

• more generic wrapping rules for Python objects based on supported protocols (callable, getitem, getattr)

• new helper functions as_attrgetter() and as_itemgetter() to specify the Python object protocol used by Lua indexing when wrapping Python objects in Python code

• new helper functions python.as_attrgetter(), python.as_itemgetter() and python.as_function() to specify the Python object protocol used by Lua indexing of Python objects in Lua code

• item and attribute access for Python objects from Lua code

0.12 (2010-08-16)

• fix Lua stack leak during table iteration

• fix lost Lua object reference after iteration

0.11 (2010-08-07)

• error reporting on Lua syntax errors failed to clean up the stack so that errors could leak into the next Lua run

• Lua error messages were not properly decoded

0.10 (2010-07-27)

• much faster locking of the LuaRuntime, especially in the single threaded case (see http://code.activestate.com/recipes/577336-fast-re-entrant-optimistic-lock-implemented-in-cyt/)

• fixed several error handling problems when executing Python code inside of Lua

0.9 (2010-07-23)

• fixed Python special double-underscore method access on LuaObject instances

• Lua coroutine support through dedicated wrapper classes, including Python iteration support. In Python space, Lua coroutines behave exactly like Python generators.

0.8 (2010-07-21)

• support for returning multiple values from Lua evaluation

• repr() support for Lua objects

• LuaRuntime.table() method for creating Lua tables from Python space

• encoding fix for str(LuaObject)

0.7 (2010-07-18)

• LuaRuntime.require() and LuaRuntime.globals() methods

• renamed LuaRuntime.run() to LuaRuntime.execute()

• support for len(), setattr() and subscripting of Lua objects

• provide all built-in Lua libraries in LuaRuntime, including support for library loading

• fixed a thread locking issue

• fix passing Lua objects back into the runtime from Python space

0.6 (2010-07-18)

• Python iteration support for Lua objects (e.g. tables)

• threading fixes

• fix compile warnings

0.5 (2010-07-14)

• explicit encoding options per LuaRuntime instance to decode/encode strings and Lua code

0.4 (2010-07-14)

• attribute read access on Lua objects, e.g. to read Lua table values from Python

• str() on Lua objects

• include .hg repository in source downloads

• added missing files to source distribution

0.3 (2010-07-13)

• fix several threading issues

• safely free the GIL when calling into Lua

0.2 (2010-07-13)

• propagate Python exceptions through Lua calls

0.1 (2010-07-12)

• first public release

Lupa

Copyright (c) 2010-2017 Stefan Behnel. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Lua

(See https://www.lua.org/license.html)

Copyright © 1994–2017 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.