Managing modules | Tarantool
Check out the new release policy
Administration Managing modules

Managing modules

This section covers the installation and reloading of Tarantool modules. To learn about writing your own module and contributing it, check the Contributing a module section.

Modules in Lua and C that come from Tarantool developers and community contributors are available in the following locations:

  • Tarantool modules repository (see below)
  • Tarantool deb/rpm repositories (see below)

See README in tarantool/rocks repository for detailed instructions.

Follow these steps:

  1. Install Tarantool as recommended on the download page.

  2. Install the module you need. Look up the module’s name on Tarantool rocks page and put the prefix “tarantool-” before the module name to avoid ambiguity:

    $ # for Ubuntu/Debian:
    $ sudo apt-get install tarantool-<module-name>
    $ # for RHEL/CentOS/Amazon:
    $ sudo yum install tarantool-<module-name>

    For example, to install the module shard on Ubuntu, say:

    $ sudo apt-get install tarantool-shard

Once these steps are complete, you can:

  • load any module with

    tarantool> name = require('module-name')

    for example:

    tarantool> shard = require('shard')
  • search locally for installed modules using package.path (Lua) or package.cpath (C):

    tarantool> package.path
    - ./?.lua;./?/init.lua; /usr/local/share/tarantool/?.lua;/usr/local/share/
    tarantool> package.cpath
    - ./?.so;/usr/local/lib/x86_64-linux-gnu/tarantool/?.so;/usr/lib/x86_64-li


    Question-marks stand for the module name that was specified earlier when saying require('module-name').

You can reload any Tarantool application or module with zero downtime.

Here’s an example that illustrates the most typical case – “update and reload”.


In this example, we use recommended administration practices based on instance files and tarantoolctl utility.

  1. Update the application file.

    For example, a module in /usr/share/tarantool/app.lua:

    local function start()
      -- initial version
      box.once("myapp:v1.0", function()"somedata")"primary")
      -- migration code from 1.0 to 1.1
      box.once("myapp:v1.1", function()
      -- migration code from 1.1 to 1.2
      box.once("myapp:v1.2", function()
    -- start some background fibers if you need
    local function stop()
      -- stop all background fibers and clean up resources
    local function api_for_call(xxx)
      -- do some business
    return {
      start = start,
      stop = stop,
      api_for_call = api_for_call
  2. Update the instance file.

    For example, /etc/tarantool/instances.enabled/my_app.lua:

    #!/usr/bin/env tarantool
    -- hot code reload example
    box.cfg({listen = 3302})
    -- ATTENTION: unload it all properly!
    local app = package.loaded['app']
    if app ~= nil then
      -- stop the old application version
      -- unload the application
      package.loaded['app'] = nil
      -- unload all dependencies
      package.loaded['somedep'] = nil
    -- load the application'require app')
    app = require('app')
    -- start the application
    app.start({some app options controlled by sysadmins})

    The important thing here is to properly unload the application and its dependencies.

  3. Manually reload the application file.

    For example, using tarantoolctl:

    $ tarantoolctl eval my_app /etc/tarantool/instances.enabled/my_app.lua

After you compiled a new version of a C module (*.so shared library), call box.schema.func.reload(‘module-name’) from your Lua script to reload the module.

Found what you were looking for?