Guide · Open source
How to use kcp: build a reliable UDP protocol in C
Updated · written with AI from the project's own documentation and checked against our catalogue data
kcp is an open-source ARQ protocol written in C that makes UDP packets arrive reliably by resending lost data and acknowledging receipt. It is a library, not an app: it has no user interface and does not send or receive packets itself. This guide shows what you need, how to clone and build it, and how to wire it into your own UDP code.
KCPskywind3000/kcp · ★ 17k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone https://github.com/skywind3000/kcp to get the source.
- 2Add the two source files. Copy ikcp.h and ikcp.c into your own C project.
- 3Create the kcp object. Call ikcp_create with a conv number shared by both peers and a user pointer.
- 4Set the output callback. Write a udp_output function that sends the buffer over your UDP socket, and assign it to kcp->output.
- 5Drive the state machine. Call ikcp_update every few milliseconds and pass received UDP packets to ikcp_input.
- 6Send and receive data. Use ikcp_send on one end and ikcp_recv on the other.
- 7Tune the settings. Adjust ikcp_nodelay, ikcp_wndsize and ikcp_setmtu to suit your latency and bandwidth needs.
What you need before you start
kcp is a building block for developers who already write UDP-based networking code. The source says the protocol consists of two files, ikcp.h and ikcp.c, which you can copy into an existing project.
- A C compiler
- Git
- Your own UDP send and receive code, plus a clock in milliseconds
Install kcp by cloning and building it
The install method is clone-and-build. The README gives the clone command below. Compile the two source files with your own project, as the README describes.
- Install a C compiler and Git.
- Clone the repository.
- Add ikcp.h and ikcp.c to your project.
git clone https://github.com/skywind3000/kcpCreate a kcp object and set the output callback
Each kcp object is created with a conv number and a user pointer. Both sides of a connection must use the same conv, or packets will not be accepted. The output callback is the function kcp calls when it needs to send data over your UDP layer.
- Call ikcp_create(conv, user) to create the object.
- Write a udp_output function with the buf, len, kcp and user parameters.
- Assign it with kcp->output = udp_output.
ikcpcb *kcp = ikcp_create(conv, user);
int udp_output(const char *buf, int len, ikcpcb *kcp, void *user)
{
....
}
kcp->output = udp_output;Call update in a loop and feed in received packets
kcp needs to be driven from outside. Call ikcp_update regularly with the current time in milliseconds, for example every 10 ms. The README notes you can use ikcp_check to find when the next update is needed instead of calling it every time. When a lower-layer packet such as a UDP packet arrives, pass it to ikcp_input.
After this, use ikcp_send to send data and ikcp_recv on the other end to receive it. The source notes that kcp does not make any system calls internally, because the clock is passed in from outside.
- ikcp_update(kcp, millisec) updates the state.
- ikcp_input(kcp, received_udp_packet, received_udp_size) handles incoming packets.
- ikcp_send sends data and ikcp_recv receives it.
ikcp_update(kcp, millisec);
ikcp_input(kcp, received_udp_packet, received_udp_size);Tune kcp for low latency or the default mode
By default kcp behaves like a standard ARQ. You turn on speed features with ikcp_nodelay, which takes nodelay, interval, resend and nc. The README gives a normal mode and a fast mode as examples. You can also set window sizes with ikcp_wndsize, which defaults to 32 packets, and change the MTU with ikcp_setmtu, which defaults to 1400 bytes.
- Normal mode: ikcp_nodelay(kcp, 0, 40, 0, 0);
- Fast mode: ikcp_nodelay(kcp, 1, 10, 2, 1);
- The README says the minimum RTO can be changed with kcp->rx_minrto = 10;
ikcp_nodelay(kcp, 0, 40, 0, 0);
ikcp_nodelay(kcp, 1, 10, 2, 1);Know the trade-offs before you commit
The README says kcp wastes 10%-20% more bandwidth than TCP in exchange for lower latency. It describes this as a design for flow speed rather than total throughput. The source also says the fast-mode setting trades some fairness and bandwidth use for speed. Check whether your project can accept that extra bandwidth use.
- Good fit: small, time-sensitive messages and games or real-time media that can accept extra bandwidth use.
- Poor fit: tight bandwidth budgets, or projects that want a finished app.
- The README's documentation index links to wiki pages on best practice, encryption and TCP integration.
What people use it for
- A game client and server that send small, frequent messages over UDP and need reliable delivery.
- A custom peer-to-peer or UDP-based protocol that lacks a built-in ARQ layer.
- Real-time media transport where latency matters more than bandwidth.
- Porting a protocol stack to another language, using the existing kcp ports listed in the README.
Frequently asked questions
Is kcp free to use?
kcp is released under the MIT licence, according to the repository's licence badge. The README does not describe pricing. Check the LICENSE file in the repository for the full terms.
What do I need to install kcp?
The source lists a C compiler and Git as prerequisites. You clone the repository and add ikcp.h and ikcp.c to your project.
Does kcp send packets by itself?
No. The README says kcp does not send or receive packets. Your program supplies the UDP send and receive code and the clock.
Is kcp faster than TCP?
The README says kcp trades 10%-20% extra bandwidth for lower latency than TCP, and gives figures for average and maximum latency. These are the README's claims. Test with your own workload before relying on them.
What are alternatives to kcp?
The repository lists quic-go, enet, libjingle and RakNet as comparable projects. Pick based on whether you need a ready-made transport or a small C building block.
Why does kcp waste bandwidth?
The README says kcp favours flow speed over bandwidth efficiency. Its fast mode skips some congestion control steps, which trades fairness and bandwidth use for speed.
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
kcp suits developers who are building their own UDP protocol and need reliable, low-latency delivery in C or a port of it. It is a poor choice if you want a finished app, have tight bandwidth limits, or do not want to write the UDP glue and update loop yourself.
Install options & downloads