Skip to content
Get packs

Guide · Open source

How to use libuv: build, install and run async I/O in C

Updated · written with AI from the project's own documentation and checked against our catalogue data

libuv is a C library for asynchronous input and output. It lets a program run networking, file system work and child processes without blocking on each one, and it presents the same interface on Linux, macOS and Windows. This guide covers how to install or build it, where to find its documentation and tests, and what it is and is not suited for.

libuvlibuv/libuv · ★ 27.3k · MIT

Quick start

  1. 1Choose an install route. Pick Homebrew, vcpkg or Conan if you want a package, or build from source with autotools or CMake.
  2. 2Install prerequisites. Make sure you have a C compiler, autotools or CMake, and Git. On Windows, CMake is required.
  3. 3Run the install command. Use the command for your chosen route, such as brew install --HEAD libuv.
  4. 4Build and test from source (optional). Run the autotools or CMake steps, then run make check or the CMake tests.
  5. 5Read the documentation. Open the docs at docs.libuv.org or build them locally with make html.
  6. 6Study the tests. Look at the files in test/ for usage examples of the API.

What libuv does and who it is for

libuv is a multi-platform support library focused on asynchronous I/O. It was primarily developed for Node.js and is also used by Luvit, Julia and uvloop.

It is a low-level library. It provides primitives such as an event loop, TCP and UDP sockets, DNS resolution, file system operations and a thread pool. It does not provide a high-level framework with HTTP routing or ORM features.

  • Full-featured event loop backed by epoll, kqueue, IOCP and event ports
  • Asynchronous TCP and UDP sockets and DNS resolution
  • Asynchronous file and file system operations and file system events
  • Child processes, signal handling and a thread pool
  • IPC with socket sharing over Unix domain sockets or Windows named pipes
  • Threading and synchronization primitives

Install libuv with a package manager

The README lists three package-manager options. Each one is a single command once the package manager itself is set up.

The Homebrew command builds the HEAD version. Conan can install pre-built binaries or build from source. The vcpkg route first requires cloning the vcpkg repository and running its bootstrap script for your shell.

  • Homebrew (HEAD build)
  • vcpkg
  • Conan
$ brew install --HEAD libuv $ ./vcpkg install libuv $ conan install --requires="libuv/[*]" --build=missing

Build libuv from source on Unix-like systems

For UNIX-like platforms, including macOS, you can build with autotools or CMake. The prerequisites are a C compiler, autotools or CMake, and Git.

The autotools steps are below. To build with CMake instead, generate a project with tests enabled, then build it with cmake --build.

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

Build libuv on Windows

On Windows, CMake is the only supported build method. The README lists Visual C++ Build Tools and several Visual Studio versions as options, and asks for Git for Windows to provide basic Unix tools needed by some tests.

Run the tests after building. Some tests are timing sensitive, so the README suggests a timeout multiplier on slow machines.

  • Install Visual C++ Build Tools or a supported Visual Studio edition
  • Install Git for Windows for Git Bash and the Unix tools used by some tests
$ cmake -B build -DBUILD_TESTING=ON $ cmake --build build $ (cd build && ctest -C Debug --output-on-failure)

Read the docs and use the tests as examples

The official documentation is in the docs/ subdirectory and uses Sphinx. Run make help to see the build options. The README notes that tests and benchmarks also serve as API specification and usage examples. The test list is in test/test-list.h and the benchmark list is in test/benchmark-list.h.

The README says the third-party resources it links to are not maintained by libuv maintainers and may be out of date, so check them before reporting issues.

  • Online documentation is at docs.libuv.org
  • Build HTML docs with make html; live reload needs sphinx-autobuild and works on Unix only
  • Other resources include an LXJS 2012 introductory talk, libuv-dox and learnuv
$ make help $ make html

Check licence, versioning and platform support

libuv is licensed under the MIT license, and its documentation is under CC BY 4.0. Starting with version 1.0.0 it follows semantic versioning and promises a stable ABI across major releases.

Platform details are in the SUPPORTED_PLATFORMS file. The README also recommends the -fno-strict-aliasing compiler flag for projects that use libuv.

What people use it for

  • Building networked servers or clients in C that need non-blocking TCP or UDP sockets
  • Running file system operations without blocking the main thread
  • Writing a language runtime or binding that needs an event loop, as Node.js, Julia and uvloop do
  • Studying how event loops work using the libuv test suite and benchmarks

Frequently asked questions

Is libuv free to use?

Yes. libuv is licensed under the MIT license. The documentation is licensed under CC BY 4.0. Check the LICENSE and LICENSE-extra files in the repository.

How do I install libuv?

The README lists Homebrew (brew install --HEAD libuv), vcpkg (./vcpkg install libuv) and Conan (conan install --requires="libuv/[*]" --build=missing). You can also build from source with autotools or CMake.

What do I need to build libuv?

You need a C compiler, autotools or CMake, and Git. On Windows, CMake is the only supported build method and you need Visual C++ Build Tools or a supported Visual Studio version.

Does libuv work on Windows, macOS and Linux?

Yes. The README describes it as a multi-platform library, with epoll, kqueue, IOCP and event ports backing the event loop. Check SUPPORTED_PLATFORMS for details.

What is libuv used for?

It is mainly used for asynchronous I/O in networked and I/O-heavy software. It was built for Node.js and is also used by Julia and uvloop.

How does libuv compare to libevent, libev or Boost.Asio?

These are comparable projects for event-driven I/O. The source material does not include a benchmark comparison, so test each against your own workload before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use libuv if you are writing networked or I/O-heavy software in C, or in a language with C bindings, and need the same code to run on Linux, macOS and Windows. Pick a higher-level framework instead if you want built-in HTTP routing or ORM features, or if you need an end-user application rather than a library.

Install options & downloads