Skip to content
Cross-platform asynchronous I/O
C C++ Python Makefile M4 CMake Other
Branch: v1.x
Clone or download
bnoordhuis unix: cache address of dlsym("mkostemp")
Look up the "mkostemp" symbol once instead of on every call
to uv_fs_mkstemp().

PR-URL: #2564
Reviewed-By: Anna Henningsen <>
Reviewed-By: Colin Ihrig <>
Reviewed-By: Richard Lau <>
Reviewed-By: Santiago Gimeno <>
Reviewed-By: Saúl Ibarra Corretgé <>
Latest commit a0530ce Dec 8, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github misc: enable stalebot Aug 9, 2019
docs fs: add uv_fs_mkstemp Dec 3, 2019
img img: add logo files Jul 20, 2014
include Now working on version 1.34.1 Dec 4, 2019
m4 build: fix utf-8 name of copyright holder Apr 29, 2018
samples samples: fix inconsistency in parse_opts vs usage Jun 15, 2018
src unix: cache address of dlsym("mkostemp") Dec 8, 2019
test fs: add uv_fs_mkstemp Dec 3, 2019
tools win,build: bump vswhere_usability_wrapper to 2.0.0 Sep 25, 2017
.gitattributes unix: make uv_fs_read() fill all buffers Jun 20, 2019
.gitignore win: add UV_FS_O_FILEMAP Jul 16, 2019
.mailmap 2019.08.10, Version 1.31.0 (Stable) Aug 9, 2019
AUTHORS 2019.12.05, Version 1.34.0 (Stable) Dec 4, 2019
CMakeLists.txt build: fix android build, add missing sources Nov 19, 2019 build: add test suite option to cmake build Jun 14, 2018
ChangeLog Add SHA to ChangeLog Dec 4, 2019
LICENSE misc: remove reference to pthread-fixes.h from LICENSE Jul 24, 2017
LICENSE-docs doc: change license to CC BY 4.0 Apr 28, 2017 doc: add richardlau to maintainers Nov 26, 2019 build: fix android autotools build Nov 19, 2019 aix: Fix broken cmpxchgi() XL C++ specialization. Sep 6, 2019 doc: remove old FreeBSD 9 related note Oct 15, 2019
android-configure-arm build: add compile for android arm64/x86/x86-64 Sep 17, 2018
android-configure-arm64 build: add compile for android arm64/x86/x86-64 Sep 17, 2018
android-configure-x86 build: add compile for android arm64/x86/x86-64 Sep 17, 2018
android-configure-x86_64 build: add compile for android arm64/x86/x86-64 Sep 17, 2018
appveyor.yml win,build: do not build executable installer for dll Jan 16, 2018 build: invoke libtoolize with --copy Jan 5, 2016
common.gypi build: add support for 64-bit AIX Apr 22, 2018 2019.12.05, Version 1.34.0 (Stable) Dec 4, 2019 build: split off tests into separate gyp file Jan 27, 2018 build: add a cmake build file Jun 14, 2018
uv.gyp build: fix android build, fix symbol redefinition Nov 19, 2019
vcbuild.bat build: split off tests into separate gyp file Jan 27, 2018



libuv is a multi-platform support library with a focus on asynchronous I/O. It was primarily developed for use by Node.js, but it's also used by Luvit, Julia, pyuv, and others.

Feature highlights

  • Full-featured event loop backed by epoll, kqueue, IOCP, event ports.

  • Asynchronous TCP and UDP sockets

  • Asynchronous DNS resolution

  • Asynchronous file and file system operations

  • File system events

  • ANSI escape code controlled TTY

  • IPC with socket sharing, using Unix domain sockets or named pipes (Windows)

  • Child processes

  • Thread pool

  • Signal handling

  • High resolution clock

  • Threading and synchronization primitives


Starting with version 1.0.0 libuv follows the semantic versioning scheme. The API change and backwards compatibility rules are those indicated by SemVer. libuv will keep a stable ABI across major releases.

The ABI/API changes can be tracked here.


libuv is licensed under the MIT license. Check the LICENSE file. The documentation is licensed under the CC BY 4.0 license. Check the LICENSE-docs file.



Official documentation

Located in the docs/ subdirectory. It uses the Sphinx framework, which makes it possible to build the documentation in multiple formats.

Show different supported building options:

$ make help

Build documentation as HTML:

$ make html

Build documentation as HTML and live reload it when it changes (this requires sphinx-autobuild to be installed and is only supported on Unix):

$ make livehtml

Build documentation as man pages:

$ make man

Build documentation as ePub:

$ make epub

NOTE: Windows users need to use make.bat instead of plain 'make'.

Documentation can be browsed online here.

The tests and benchmarks also serve as API specification and usage examples.

Other resources

  • LXJS 2012 talk — High-level introductory talk about libuv.
  • libuv-dox — Documenting types and methods of libuv, mostly by reading uv.h.
  • learnuv — Learn uv for fun and profit, a self guided workshop to libuv.

These resources are not handled by libuv maintainers and might be out of date. Please verify it before opening new issues.


libuv can be downloaded either from the GitHub repository or from the downloads site.

Starting with libuv 1.7.0, binaries for Windows are also provided. This is to be considered EXPERIMENTAL.

Before verifying the git tags or signature files, importing the relevant keys is necessary. Key IDs are listed in the MAINTAINERS file, but are also available as git blob objects for easier use.

Importing a key the usual way:

$ gpg --keyserver --recv-keys AE9BC059

Importing a key from a git blob object:

$ git show pubkey-saghul | gpg --import

Verifying releases

Git tags are signed with the developer's key, they can be verified as follows:

$ git verify-tag v1.6.1

Starting with libuv 1.7.0, the tarballs stored in the downloads site are signed and an accompanying signature file sit alongside each. Once both the release tarball and the signature file are downloaded, the file can be verified as follows:

$ gpg --verify libuv-1.7.0.tar.gz.sign

Build Instructions

For GCC there are two build methods: via autotools or via GYP. GYP is a meta-build system which can generate MSVS, Makefile, and XCode backends. It is best used for integration into other projects.

To build with autotools:

$ sh
$ ./configure
$ make
$ make check
$ make install

To build with CMake:

$ mkdir -p out/cmake ; cd out/cmake   # create build directory
$ cmake ../.. -DBUILD_TESTING=ON      # generate project with test
$ cmake --build .                     # build
$ ctest -C Debug --output-on-failure  # run tests

# Or manually run tests:
$ ./out/cmake/uv_run_tests    # shared library build
$ ./out/cmake/uv_run_tests_a  # static library build

To build with GYP, first run:

$ git clone build/gyp



  • Python 2.6 or 2.7 as it is required by GYP. If python is not in your path, set the environment variable PYTHON to its location. For example: set PYTHON=C:\Python27\python.exe
  • One of:
    • Visual C++ Build Tools
    • Visual Studio 2015 Update 3, all editions including the Community edition (remember to select "Common Tools for Visual C++ 2015" feature during installation).
    • Visual Studio 2017, any edition (including the Build Tools SKU). Required Components: "MSbuild", "VC++ 2017 v141 toolset" and one of the Windows SDKs (10 or 8.1).
  • Basic Unix tools required for some tests, Git for Windows includes Git Bash and tools which can be included in the global PATH.

To build, launch a git shell (e.g. Cmd or PowerShell), run vcbuild.bat (to build with VS2017 you need to explicitly add a vs2017 argument), which will checkout the GYP code into build/gyp, generate uv.sln as well as the necesery related project files, and start building.

> vcbuild


> vcbuild vs2017

To run the tests:

> vcbuild test

To see all the options that could passed to vcbuild:

> vcbuild help
vcbuild.bat [debug/release] [test/bench] [clean] [noprojgen] [nobuild] [vs2017] [x86/x64] [static/shared]
  vcbuild.bat              : builds debug build
  vcbuild.bat test         : builds debug build and runs tests
  vcbuild.bat release bench: builds release build and runs benchmarks


For Debug builds (recommended) run:

$ ./ -f make
$ make -C out

For Release builds run:

$ ./ -f make
$ BUILDTYPE=Release make -C out

Run ./ -f make -Dtarget_arch=x32 to build x32 binaries.



$ ./ -f xcode
$ xcodebuild -ARCHS="x86_64" -project out/uv.xcodeproj -configuration Release -alltargets

Using Homebrew:

$ brew install --HEAD libuv

Note to OS X users:

Make sure that you specify the architecture you wish to build for in the "ARCHS" flag. You can specify more than one by delimiting with a space (e.g. "x86_64 i386").



For arm

$ source ./android-configure-arm NDK_PATH gyp [API_LEVEL]
$ make -C out

or for arm64

$ source ./android-configure-arm64 NDK_PATH gyp [API_LEVEL]
$ make -C out

or for x86

$ source ./android-configure-x86 NDK_PATH gyp [API_LEVEL]
$ make -C out

or for x86_64

$ source ./android-configure-x86_64 NDK_PATH gyp [API_LEVEL]
$ make -C out

The default API level is 24, but a different one can be selected as follows:

$ source ./android-configure-arm ~/android-ndk-r15b gyp 21
$ make -C out

Note for UNIX users: compile your project with -D_LARGEFILE_SOURCE and -D_FILE_OFFSET_BITS=64. GYP builds take care of that automatically.

Using Ninja

To use ninja for build on ninja supported platforms, run:

$ ./ -f ninja
$ ninja -C out/Debug     #for debug build OR
$ ninja -C out/Release

Running tests


Build (includes tests):

$ ./ -f make
$ make -C out

Run all tests

$ ./out/Debug/run-tests

Run one test

The list of all tests is in test/test-list.h.

This invocation will cause the run-tests driver to fork and execute TEST_NAME in a child process:

$ ./out/Debug/run-tests TEST_NAME

This invocation will cause the run-tests driver to execute the test within the run-tests process:

$ ./out/Debug/run-tests TEST_NAME TEST_NAME

Debugging tools

When running the test from within the run-tests process (run-tests TEST_NAME TEST_NAME), tools like gdb and valgrind work normally. When running the test from a child of the run-tests process (run-tests TEST_NAME), use these tools in a fork-aware manner.

Fork-aware gdb

Use the follow-fork-mode setting:

$ gdb --args out/Debug/run-tests TEST_NAME

(gdb) set follow-fork-mode child
Fork-aware valgrind

Use the --trace-children=yes parameter:

$ valgrind --trace-children=yes -v --tool=memcheck --leak-check=full --track-origins=yes --leak-resolution=high --show-reachable=yes --log-file=memcheck-%p.log out/Debug/run-tests TEST_NAME

Running benchmarks

See the section on running tests. The benchmark driver is out/Debug/run-benchmarks and the benchmarks are listed in test/benchmark-list.h.

Supported Platforms


AIX Notes

AIX compilation using IBM XL C/C++ requires version 12.1 or greater.

AIX support for filesystem events requires the non-default IBM bos.ahafs package to be installed. This package provides the AIX Event Infrastructure that is detected by autoconf. IBM documentation describes the package in more detail.

AIX support for filesystem events is not compiled when building with gyp.

z/OS Notes

z/OS creates System V semaphores and message queues. These persist on the system after the process terminates unless the event loop is closed.

Use the ipcrm command to manually clear up System V resources.


See the guidelines for contributing.

You can’t perform that action at this time.