Managing modules | Tarantool
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 vshard on Ubuntu, say:

    $ sudo apt-get install tarantool-vshard

Once these steps are complete, you can:

  • load any module with

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

    for example:

    tarantool> vshard = require('vshard')
  • 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 tt 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 tt:

    $ tt connect my_app -f /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?