libevent: An Event Notification Library for Portable Async I/O in C

What libevent solves, and who is expected to use it

A server that handles many sockets at once cannot spend a thread per connection and cannot block on any single read. The standard answer on Linux is epoll, on the BSDs and macOS it is kqueue, on Windows it is IOCP, and on platforms that offer none of those you fall back to poll or select. Each has a different API, different edge cases and different behaviour under load. libevent exists to hide that difference behind one interface: you register a file descriptor and a callback, run a loop, and the library picks the best available mechanism underneath. The repository confirms this scope: epoll.c, devpoll.c and event_iocp.c sit next to each other in the top level, and the topics list on the project page names async, cross-platform and networking. The audience is C programmers writing network servers, proxies or clients, and C++ programmers willing to call a C API. The README points newcomers at the official site at libevent.org and at a work-in-progress manual hosted at wangafu.net, which tells you something about the documentation situation before you start.

The event loop, bufferevents and the DNS resolver

The core object is the event base, which owns the loop and the selected backend. You add events to it, each pairing a file descriptor with a callback and a set of conditions such as readable or writable. When the backend reports readiness, the loop dispatches the callbacks. That is the whole model at the lowest level, and it is close to what epoll or kqueue give you directly, which is why the library is thin enough to reason about. Above that sits the bufferevent layer. A bufferevent wraps a socket with an input buffer and an output buffer, so you write bytes and the library handles partial writes and retries rather than making you track offsets by hand. The repository shows how far that layer reaches: bufferevent_sock.c for plain sockets, bufferevent_openssl.c and bufferevent_mbedtls.c for TLS, bufferevent_filter.c for transformations in the middle, bufferevent_pair.c for in-process pairs, bufferevent_ratelim.c for rate limiting. There is also evdns.c, a DNS resolver, and event_tagging.c, plus an HTTP server and client visible in the sample directory. The honest reading is that libevent is not one library but three stacked ones: the event loop, the buffered I/O layer, and a small set of protocol helpers. Most users need the first two.

Building libevent with CMake and running the hello-world sample

The README's primary build path is CMake on Unix. The documented sequence creates a build directory, configures with default Unix Makefiles, builds, and optionally runs the test suite through a verify target. If the build succeeds you get the library plus the sample programs, and make verify is the quickest way to confirm the toolchain and the platform backend both work before you write any code of your own.

mkdir build && cd build
cmake ..     # Default to Unix Makefiles.
make
make verify  # (optional)

On Windows the README gives a parallel sequence using a Visual Studio generator, either building from the command line or opening the generated solution. The generator string is the part people get wrong; the README suggests running cmake --help to list what your installation supports.

md build && cd build
cmake -G "Visual Studio 10" ..   # Or use any generator you want to use. Run cmake --help for a list
cmake --build . --config Release # Or "start libevent.sln" and build with menu in Visual Studio.

If you would rather not build from source, the README documents vcpkg as a supported package manager. It clones the vcpkg repository, bootstraps it, integrates it with your toolchain, and then installs the libevent port. Note the README's own caveat: the port is maintained by Microsoft team members and community contributors, and if the version lags you are directed to file an issue on the vcpkg repository rather than here.

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install libevent

The third path is autoconf, and the README labels it deprecated as of 2.2. It still works and the steps are the familiar ones, but new projects should not start here.

./configure
make
make verify   # (optional)
sudo make install

For a first real program, the repository ships sample/hello-world.c, which is the smallest complete event loop in the tree. Read it before writing your own main function: it shows the event base setup, the listener registration and the dispatch call in a few dozen lines, and it is the reference the README's manual points back to.

Where libevent is the wrong tool

The most concrete limitation is the release situation. The README's release list shows release-2.1.13-stable from 2026-07-01 and release-2.2.2-alpha from the same day. The stable line and the alpha line are not the same thing, and choosing 2.2.x means accepting an alpha label on the branch that carries the newer API work. Anyone who needs a support contract or a frozen ABI should read the ChangeLog entries for both lines before deciding, because the README does not document a rollback path or a compatibility guarantee between them. A second limitation is the layer you do not get. libevent gives you an event loop and buffered sockets; it does not give you a thread pool, a process spawn API, or a filesystem abstraction. If your program needs to run blocking work without stalling the loop, libevent offers no built-in answer, and the bufferevent_async.c and event_iocp.c files show that async I/O on Windows is handled through IOCP rather than through a general worker model. Third, the documentation is genuinely thin. The README itself calls the manual work-in-progress, and the primary reference is a third-party site. Expect to read headers and sample code rather than a complete guide. Finally, the C API means manual lifetime management: you allocate and free event bases and bufferevents yourself, and a callback that frees the object it was called with is a class of bug the library cannot prevent for you.

libevent compared with libuv and libev

libuv is the closest alternative and the difference is architectural, not cosmetic. libuv was written for Node.js and ships a thread pool as part of the core, so file system operations and DNS lookups that would block have a defined place to run. It also carries process management, pipes and a larger platform abstraction. libevent keeps the loop and the buffers and leaves the threading model to you. If you want a runtime that already answers the blocking-work question, libuv is the shorter path; if you want a library that does one job and stays out of the way, libevent's smaller surface is the argument in its favour. libev is the other comparison, and the split is about scope rather than portability. libev is essentially the event loop alone, with a reputation for a compact implementation and no buffered I/O layer, no DNS resolver and no HTTP helpers. Choosing libev means writing your own buffer management on top; choosing libevent means accepting a larger library in exchange for bufferevents and evdns. The repository's own file list is the clearest evidence of which side of that trade libevent sits on.

Maintenance, licensing and the cost of upgrading

The repository is not archived and the last push was on 2026-09-01, so the project is receiving changes. That is a statement about activity, not about the stability of any particular branch. The upgrade cost is concentrated in the 2.1 to 2.2 transition. The autoconf build is deprecated as of 2.2, so a project upgrading across that line should plan to move to CMake or to a package manager, and the ChangeLog files in the repository root (ChangeLog, ChangeLog-2.0, ChangeLog-2.1) are where the API and behaviour changes are recorded. On licensing, the repository's LICENSE file is the authoritative text and GitHub reports the licence as NOASSERTION, meaning the platform could not map it to a known identifier automatically. libevent has historically been distributed under a BSD-style licence, but do not take that from a review: open LICENSE and read it, and involve your own legal review if the terms matter to your distribution model. Nothing here is legal advice.

What to check before you depend on it

Three checks are worth doing before libevent becomes a dependency. First, confirm which backend your target platform selects at build time, because the behaviour you get on Linux through epoll is not the behaviour you get through select on an older system, and the fallback path is the one that tends to be exercised least. Second, decide between the 2.1.13-stable line and the 2.2.2-alpha line deliberately, reading the relevant ChangeLog before you commit, since the README does not describe a migration path between them. Third, build sample/hello-world.c and sample/http-server.c on your actual target and run them, because the samples are the documentation that the project actually maintains. If those two programs build and run against your toolchain, the library is probably fine for your use case. If they do not, you have found the problem before writing any application code.

Editorial conclusion

Adopt libevent when you are writing C or C++ and want a single event loop that compiles against epoll, kqueue, IOCP and the older poll and select backends without per-platform code. Do not adopt it if your project is already built around libuv's thread pool and process APIs, or if you need the higher-level async model of Boost.Asio and are willing to take the C++ dependency. Before committing, verify three things: that the backend your target platform actually selects is the one you expect, that the 2.2.x line is acceptable given its alpha label, and that your build system can consume the CMake project, since the autoconf path is marked deprecated in the README.

Frequently asked questions

Official sources

1. Issues
2. libevent/libevent on GitHub
3. Project website
4. README
5. Releases