Skip to content

Netty

Asynchronous network application framework — the engine under a great deal of JVM infrastructure.

Web & HTTPWebJava
Official docs ↗GitHub ↗

What it is

Netty is an asynchronous, event-driven network application framework for rapid development of maintainable high-performance protocol servers and clients.

Netty provides abstractions for building servers and clients, handling connections, pipelines, codecs, and event-driven processing. It supports TCP, UDP, HTTP, WebSockets, and custom protocols.

Licence
Apache 2.0
Powers
gRPC-Java, Elasticsearch, Cassandra and much else

When to use it

The question documentation cannot answer for you — because it cannot recommend something else.

Reach for it when

  • Implementing a custom network protocol
  • Building a high-concurrency server where you need control over the event loop and buffers

Look elsewhere when

  • You are writing an ordinary HTTP service — use a framework built on Netty rather than Netty itself
  • Virtual threads have made simple blocking code viable for your load profile

Installation

Add io.netty:netty-all dependency in pom.xml

Getting started

The smallest useful thing you can do with it, and what each part means.

Creating a simple TCP server
import io.netty.bootstrap.ServerBootstrap;
import io.netty.channel.*;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.nio.NioServerSocketChannel;

public class SimpleServer {
    public static void main(String[] args) throws Exception {
        EventLoopGroup bossGroup = new NioEventLoopGroup(1);
        EventLoopGroup workerGroup = new NioEventLoopGroup();
        try {
            ServerBootstrap b = new ServerBootstrap();
            b.group(bossGroup, workerGroup)
             .channel(NioServerSocketChannel.class)
             .childHandler(new ChannelInitializer<Channel>() {
                 @Override
                 protected void initChannel(Channel ch) {
                     ch.pipeline().addLast(new SimpleServerHandler());
                 }
             });
            ChannelFuture f = b.bind(8080).sync();
            f.channel().closeFuture().sync();
        } finally {
            bossGroup.shutdownGracefully();
            workerGroup.shutdownGracefully();
        }
    }
}
Sets up a simple TCP server on port 8080 using Netty with a handler for incoming connections.
Creating a simple TCP client
import io.netty.bootstrap.Bootstrap;
import io.netty.channel.*;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.nio.NioSocketChannel;

public class SimpleClient {
    public static void main(String[] args) throws Exception {
        EventLoopGroup group = new NioEventLoopGroup();
        try {
            Bootstrap b = new Bootstrap();
            b.group(group)
             .channel(NioSocketChannel.class)
             .handler(new ChannelInitializer<Channel>() {
                 @Override
                 protected void initChannel(Channel ch) {
                     ch.pipeline().addLast(new SimpleClientHandler());
                 }
             });
            ChannelFuture f = b.connect("localhost", 8080).sync();
            f.channel().closeFuture().sync();
        } finally {
            group.shutdownGracefully();
        }
    }
}
Creates a simple TCP client connecting to a server on localhost:8080.

Advanced usage

Where the library earns its place over a simpler alternative.

Using pipeline and handlers
ch.pipeline().addLast(new StringDecoder(), new StringEncoder(), new CustomHandler());
Configures a pipeline with decoders, encoders, and custom handlers for processing messages.
Handling WebSocket connections
// Add WebSocketServerProtocolHandler to pipeline for WebSocket upgrade and frame handling
Demonstrates handling WebSocket connections and frames using Netty’s built-in WebSocket support.
Event-driven architecture
channel.read();
channel.writeAndFlush(msg);
Illustrates asynchronous read/write operations to handle high concurrency efficiently.
TLS/SSL support
SslContext sslCtx = SslContextBuilder.forServer(certFile, keyFile).build();
pipeline.addLast(sslCtx.newHandler(ch.alloc()));
Adds SSL/TLS encryption to a Netty pipeline for secure communication.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

ChannelException
Occurs when there is a problem binding or connecting a channel. Verify port availability and network configuration.
Decoder/Encoder errors
Ensure message formats match decoders/encoders in the pipeline.
OutOfMemoryError
Tune Netty buffer allocation and release resources properly to avoid memory leaks.

Best practices

  • Use separate EventLoopGroups for boss and worker threads to handle connections and I/O efficiently.
  • Leverage the pipeline for modular and reusable handlers.
  • Avoid blocking operations in event handlers; delegate to separate threads if necessary.
  • Use proper resource cleanup to prevent memory leaks and dangling connections.
  • Monitor and tune thread pools and buffers for high-performance network applications.

Alternatives

Comparable options, and the reason you would pick one over the other.

Background

Why it exists, and what it was reacting to.

Netty was created to simplify the development of scalable and high-performance network applications in Java. It abstracts low-level I/O operations, providing an easy-to-use API for TCP/UDP protocols and enabling event-driven architectures.

Related libraries

Others in Web & HTTP for Java.

← All Java librariesJava guide