You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Aleksey Smolenchuk d9b843c03b Upgrade `nan` to v2.12.0 (#523) 3 years ago
deps/libffi Replace "dlfcn-win32" with "simple-dlfcn-win32" 6 years ago
example factorial: fix Windows build instructions 7 years ago
lib add libffi `version` string 5 years ago
src Support Node.js 9.x (#439) 4 years ago
test test: add a test case for TooTallNate/ref#56 5 years ago
.gitignore WebStorm support in gitignore 7 years ago
.jshintrc jshintrc: enable "laxbreak" 7 years ago
.travis.yml Test Node 6, 8, 10 and 11 3 years ago Release 2.2.0 5 years ago
LICENSE package: add Gabor to LICENSE and "contributors" 6 years ago README: clarify use of acronym (#510) 3 years ago
appveyor.yml Test Node 6, 8, 10 and 11 3 years ago
binding.gyp remove OS X 10.5 deployment target 5 years ago
package-lock.json Upgrade `nan` to v2.12.0 (#523) 3 years ago
package.json Upgrade `nan` to v2.12.0 (#523) 3 years ago


Node.js Foreign Function Interface

Build Status Build Status

node-ffi is a Node.js addon for loading and calling dynamic libraries using pure JavaScript. It can be used to create bindings to native libraries without writing any C++ code.

It also simplifies the augmentation of node.js with C code as it takes care of handling the translation of types across JavaScript and C, which can add reams of boilerplate code to your otherwise simple C. See the example/factorial for an example of this use case.

WARNING: node-ffi assumes you know what you're doing. You can pretty easily create situations where you will segfault the interpreter and unless you've got C debugger skills, you probably won't know what's going on.


var ffi = require('ffi');

var libm = ffi.Library('libm', {
  'ceil': [ 'double', [ 'double' ] ]
libm.ceil(1.5); // 2

// You can also access just functions in the current process by passing a null
var current = ffi.Library(null, {
  'atoi': [ 'int', [ 'string' ] ]
current.atoi('1234'); // 1234

For a more detailed introduction, see the node-ffi tutorial page.


  • Linux, OS X, Windows, or Solaris.
  • libffi comes bundled with node-ffi; it does not need to be installed on your system.
  • The current version is tested to run on node v0.6, v0.8, v0.9 and v0.10.


Make sure you've installed all the necessary build tools for your platform, then invoke:

$ npm install ffi

Source Install / Manual Compilation

To compile from source it's easiest to use node-gyp:

$ npm install -g node-gyp

Now you can compile node-ffi:

$ git clone git://
$ cd node-ffi
$ node-gyp rebuild


The types that you specify in function declarations correspond to ref's types system. So see its docs for a reference if you are unfamiliar.

V8 and 64-bit Types

Internally, V8 stores integers that will fit into a 32-bit space in a 32-bit integer, and those that fall outside of this get put into double-precision floating point (FP) numbers. This is problematic because FP numbers are imprecise. To get around this, the methods in node-ffi that deal with 64-bit integers return strings and can accept strings as parameters.

Call Overhead

There is non-trivial overhead associated with FFI calls. Comparing a hard-coded binding version of strtoul() to an FFI version of strtoul() shows that the native hard-coded binding is orders of magnitude faster. So don't just use the C version of a function just because it's faster. There's a significant cost in FFI calls, so make them worth it.


MIT License. See the LICENSE file.