ffilupa only supports Python>=3.6 and Lua>=5.2 (no LuaJIT). ffilupa is packed with a bundle Lua, so it’s fine to have no Lua installed in the system. And ffilupa will not attempt to link against Lua libraries installed in the system during the installation. See Integrate with Other Lua Libraries.

Use pip or pipenv

$ pip install ffilupa
# or pipenv if you prefer
$ pipenv install ffilupa


This documentation is about ffilupa 4.0, which is not yet released. So you need to add option --pre to command line, e.g. pip install ffilupa --pre.


If there comes a installation error saying that some modules are missing, maybe you are installing the source distribution rather than pre-built wheels. (ffilupa releases wheels covering almost all common environments. So this situation is rare.) In this case, it’s necessary to install the dependencies of ffilupa in advance:

$ pip install -r

Get the Source Code

$ git clone --recurse-submodules


This documentation is about ffilupa 4.0, which is not in the default branch. So you need to checkout the branch next or add -b next to clone command line.

Integrate with Other Lua Libraries


You can skip this section.

By default the bundle Lua is used, the version of which is 5.3. If you want ffilupa to use other Lua libraries installed in the system or built by yourself, you can manually add them after installation.

For example, Bob hates Lua 5.3 and sticks to Lua 5.2. Bob uses Ubuntu, and he has already installed the package liblua5.2-dev by apt. (Only liblua5.2-0 or lua5.2 is not enough. ffilupa needs the development files.) Then open the Python REPL: (There’s no CLI to do this stuff because I don’t think it’ll simplify anything.)

>>> from ffilupa.lualibs.builder import *       # import the builder API
>>> p = pkginfo_from_pkgconfig("lua52")         # just like ``pkg-config lua52``
>>>                                             # you can get pkg names from ``pkg-config --list-all``
>>> add_lua_pkg(p)                              # build "bridge" and add lua52 to ffilupa

See also the reference of builder API.

For other Linux distribution, there’s no distinguishing difference. For macOS, you can use Homebrew to install Lua and pkg-config. For Windows, unfortunately there’s no such thing like pkg-config.

After adding lua libraries to ffilupa, you can select one to use:

>>> from ffilupa import *
>>> lualib = get_lualibs()[1]       # index 0 is the bundle lua
>>> lua = LuaRuntime(lualib=lualib)

See also the reference of lualibs API.

Another situation is to use a Lua library built by yourself. For example, John uses a Linux distribution that has no pre-built lua package. John built Lua by himself, (well I don’t want to talk about how to build Lua,) and casually put it in the home directory:

├── include
│   ├── lauxlib.h
│   ├── lua.h
│   ├── lua.hpp
│   ├── luaconf.h
│   └── lualib.h
├── lib
│   └──
└── bin
    ├── lua
    └── luac

Then open the Python REPL:

>>> from ffilupa.lualibs.builder import *
>>> from packaging.version import Version
>>> p = PkgInfo(                                    # construct PkgInfo manually
...     version=Version('5.3.5'),                   # John built Lua 5.3.5, e.g.
...     include_dirs=('/home/john/lua/include',),   # must be tuple, not list, and do not forget the comma in brackets!
...     library_dirs=('/home/john/lua/lib',),
...     runtime_library_dirs=('/home/john/lua/lib',),
...     libraries=('lua',),
... )
>>> add_lua_pkg(p)

Finished. You can even do this on Windows.