Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


To install, you'll need Lua (binary + library) and LuaRocks.

If you have Python and Pip, you can get Lua and LuaRocks using hererocks, written by Peter Melnichenko.

  pip install hererocks
  hererocks here --lua 5.1 --luarocks 2.2

This command installs Lua and LuaRocks locally to directory here. To activate it, add here/bin to PATH:

  export PATH="$(pwd)/here/bin/:$PATH"

Then you can use commands lua, luarocks, and tools installed by luarocks.

To build and install annoy, type:

  luarocks make


See the main README.

Lua code example

local annoy = require "annoy"

local f = 3
local t = annoy.AnnoyIndex(f) -- Length of item vector that will be indexed
for i = 0, 999 do
  local v = {math.random(), math.random(), math.random()}
  t:add_item(i, v)

t:build(10) -- 10 trees

-- ...

local u = annoy.AnnoyIndex(f)
u:load('test.ann') -- super fast, will just mmap the file

-- find the 10 nearest neighbors
local neighbors = u:get_nns_by_item(0, 10)
for rank, i in ipairs(neighbors) do
  print("neighbor", rank, "is", i)

Full Lua API

Lua API closely resembles Python API, see main README. Lua binding does not support multithreaded build.


File test/annoy_test.lua is the literal translation of test/ from Python+Nosetests to Lua+Busted.

To run tests, you need Busted, Elegant Lua unit testing. To install it, type:

  luarocks install busted

To run tests, type:

  busted test/annoy_test.lua

It will take few minutes to execute.


There might be some memory leaks if inputs are incorrect. Some functions allocate stack objects calling Lua functions throwing Lua errors (e.g., luaL_checkinteger). A Lua error may omit calling C++ destructors when unwinding the stack. (If it does, depends on the Lua implementation and platform being in use.)

Lua binding was written by Boris Nagaev. You can contact me via email (see