Skip to content
Harfbuzz bindings for Lua
C Lua Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Update URL to ufyTeX organisation Jul 31, 2019
fixtures Expose glyph flags Dec 7, 2018
fonts Wrap color glyph PNG API Dec 7, 2018
scripts Expose glyph flags Dec 7, 2018
spec Fix typo in face_ot_layout_find_feature() Jun 24, 2019
src Update URL to ufyTeX organisation Jul 31, 2019
status Update full API list Jul 31, 2019
.busted Clean up busted config. Fix #34 Oct 16, 2016
.gitignore Add sample PDFs for text generated with luaharfbuzz. Jan 2, 2016
.luacheckrc Fixing luacheck warnings Jan 1, 2016
LICENSE Updating year in LICENSE Jan 6, 2016
Makefile Upgrade to 0.0.6 Jan 11, 2017 Typo Jul 31, 2019
THANKS Adding THANKS file Dec 1, 2015
luaharfbuzz-1.1.0-1.rockspec Update release Jul 31, 2019
luaharfbuzz-scm-1.rockspec Use rockspec 3.0 format Jul 31, 2019


Lua bindings for Harfbuzz.



HarfBuzz is an OpenType text shaping engine. It is used in software like Qt, Pango, Firefox, Chromium, XeTeX and LibreOffice.

luaharfbuzz provides bindings for the most common types in Harfbuzz. The initial motivation for building it was to use Harfbuzz with the LuaTeX typesetting system. However, the module isn’t tied to LuaTeX in any way. It can be used with any Lua codebase.

luaharfbuzz is currently being used inside HarfTeX, a TeX engine built on top of LuaTeX and designed to use Harfbuzz for shaping text. For more details read this TUGboat journal article titled Bringing world scripts to LuaTeX: The HarfBuzz experiment

Installing Harfbuzz

Make sure Harfbuzz libraries and headers are installed. before trying to install luaharfbuzz


Install via Homebrew

brew install harfbuzz

Ubuntu Linux

apt-get install libharfbuzz0b libharfbuzz-dev

Other Platforms

Send a pull request if you want to include specific instructions to install Harfbuzz on your preferred platform.

Before building the package, LuaRocks populates the HARFBUZZ_INCDIR and HARFBUZZ_LIBDIR to point to the correct locations. If you can populate these variables manually before running LuaRocks, you can install luaharfbuzz on any system that supports Lua and Harfbuzz.

Installing luaharfbuzz


If Luarocks and Harfbuzz are installed, luaharfbuzz can be installed like this:

luarocks install luaharfbuzz


Sample Code

Here is some sample code, showcasing the core types and methods in the API.

local harfbuzz = require('harfbuzz')
local serpent  = require('serpent') -- luarocks install serpent

-- Harfbuzz API Version
print("Harfbuzz API version", harfbuzz.version())

-- Shapers available
print("Shapers:", serpent.line({ harfbuzz.shapers() }, {comment = false}))

-- harfbuzz.Face
local face ='../fonts/notonastaliq.ttf')
print('\nFace upem = '..face:get_upem())

-- harfbuzz.Font
local font =
local xs, xy = font:get_scale()
print("\nDefault font scale = X: "..xs..", Y: "..xy)

-- harfbuzz.Buffer
local text = "یہ" -- U+06CC U+06C1
local buf =

-- harfbuzz.shape (Shapes text)
print("\nShaping '"..text.."' set with Noto Nastaliq Urdu")
harfbuzz.shape(font, buf, { language ="urd"), script ="Arab"), direction = harfbuzz.Direction.RTL})

local glyphs = buf:get_glyphs()
print("No. of glyphs", #glyphs)
print(serpent.line(glyphs, {comment = false}))

local opts = { language ="eng"), script ="Latn"), direction = harfbuzz.Direction.LTR }
local amiri_face ='../fonts/amiri-regular.ttf')
local amiri_font =

-- shaping '123' w/o features
print("\nShaping '123' set with Amiri Regular and no features")
harfbuzz.shape(amiri_font, buf, opts)
glyphs = buf:get_glyphs()
print(serpent.line(glyphs, {comment = false}))

-- shaping '123' with '+numr' (numerators)
print("\nShaping '123' set with Amiri Regular with 'numr' feature turned on")
opts.features = "+numr"
harfbuzz.shape(amiri_font, buf, opts)
glyphs = buf:get_glyphs()
print(serpent.line(glyphs, {comment = false}))



You can build the package for development purposes using LuaRocks as well. It is recommended that you build it to your local tree (using --local) to isolate it from your actual installation.

luarocks --local make

Testing and Linting

In order to make changes to the code and run the tests, the following dependencies need to be installed:

  • Bustedluarocks install busted
  • luacheckluarocks install luacheck
  • luacovluarocks install luacov
  • ldocluarocks install ldoc

Run the test suite:

make spec

Lint the codebase:

make lint

Generate documentation from sources:

make doc


Open a Github issue, or email me at

You can’t perform that action at this time.