Overview

Libwebsockets (LWS) is a flexible, lightweight pure C library for implementing modern network protocols easily with a tiny footprint, using a nonblocking event loop. It has been developed continuously since 2010 and is used in tens of millions of devices and by thousands of developers around the world.

LWS is Free Software using the MIT license.

Getting started

git clone https://libwebsockets.org/repo/libwebsockets

Browse git: v4.5, main.
100 minimal examples: v4.5, main.
Doxygen API docs: v4.5, main.
Demo server: Simple demo server

LWS roles

LWS Core code handles generic socket lifecycle, tls, vhosts, service threads, timers, unix domain sockets, SOCKS5 etc. "Roles" are wire protocol implementations on top of that, isolated via an ops struct:

Role	Client	Server
http/1.x	⭘	⭘
http/2	⭘	⭘
http/3	⭘	⭘
websockets	⭘	⭘
ws-over-h2	⭘	⭘
ws-over-h3	⭘	⭘
webtransport	⭘	⭘
raw tcp / udp / file	⭘	⭘
MQTT	⭘	⨯

LWS supports optional TLS for client or server (including client certs) on any role.

New roles can be added cleanly to lws.

TLS support (main)

TLS	Yes	No
GnuTLS	h1,h2,h3,wss,DTLS
OpenSSL	h1,h2,wss,DTLS	h3
LibreSSL	h1,h2,h3,wss,DTLS
AWS-LC	h1,h2,h3,wss,DTLS
BoringSSL	h1,h2,h3,wss,DTLS
wolfSSL	h1,h2,h3,wss,DTLS
Schannel	h1,h2,h3,wss,DTLS
mbedTLS	h1,h2,wss,DTLS	h3
BearSSL	h1,h2,wss	h3,DTLS

All support client + server, http/1, http/2 and wss-over-h2. BearSSL: no DTLS or QUIC/h3. Mbedtls: no QUIC/h3. OpenSSL: incompatible QUIC/h3. Others: h3, wss-over-h3, WT, DTLS.

LWS Protocols

User code interfaces to LWS roles by providing a "protocol", including callback for events the code is interested in customizing.

Event loop libraries

LWS defaults to using poll(), however glib, libuv, libevent and libev event libraries are all supported. LWS may both provide an internal loop, or participate cleanly in an external, "foreign" loop. New event libs can be added cleanly to lws.

LWS user code does not have to be customized depending on the event loop in use. For example LWS provides a generic high-resolution timer for each connection to arrange for delayed callbacks, hiding the details of the exact implementation depending on the chosen event loop.

Lws can coexist cleanly with an existing event loop library's loop, and be created and destroyed without disturbing the loop operation.

Platforms

LWS is available for unix-style platforms like Linux and BSD (including Mac), and also for Windows and even ESP32 and FreeRTOS.

CMake is used to configure the sources for the platform it finds itself building on, and cross-build is also supported.

Scalability

LWS uses a singlethreaded nonblocking event loop, but it also supports having n of these in n threads, spreading the connections between them by allocating them to the least busy service thread, providing scalability to hundreds of thousands of connections in a single instance.

QA

LWS uses SAI CI to test pushes on 269 builds across Linux/gcc, Mac/clang, Windows, ESP32, and OpenBSD, all built with -Wall, -Werror and -Wextra.

Support

Look through the minimal examples and the docs.
Then: Mailing List.