gnet: an event-driven transport layer that stops below your protocol

Two install commands, and two disagreeing minimum Go versions

The project ships as a Go module, and Go Modules is the recommended route. Two commands are given, one per major version line. For the current line the import path carries a v2 suffix, and for the older line it does not, so a snippet copied from a mismatched tutorial resolves a different package than the one you meant.

go get -u github.com/panjf2000/gnet/v2

go get -u github.com/panjf2000/gnet

Those two lines are the whole installation story. There is no vendor directory, no binary distribution, and no system package in the instructions. The surrounding text adds three more invocations that run through the ordinary toolchain: go mod download or go mod tidy to fetch dependencies, and go build, go run, or go test to compile. Nothing has to be installed first.

The version story is where two statements part ways. The prose asks for Go Modules with Go 1.11 or newer. The module file at the repository root declares a different floor: go 1.20. Its dependency block also holds two modules below their newest releases, and comments give the reason, golang.org/x/sync stopping at v0.11.0 and golang.org/x/sys stopping at v0.30.0 because the next versions require Go 1.23 or newer. The module is pinned back on purpose to keep the older toolchain usable.

TLS, io_uring, and KCP are three unchecked roadmap boxes

Three entries on the roadmap are drawn as empty checkboxes: TLS support, io_uring support, and KCP support. Each is a capability a reader might reasonably assume a transport framework already has, and each is absent from the current release. The TLS gap is the sharpest. There is no encryption inside the framework, so a service that needs it must terminate TLS somewhere in front of gnet or run cleartext on the wire. io_uring being unchecked means the event loop rests on epoll and kqueue only, the two mechanisms named in the introduction, with no second path. KCP being unchecked means there is no reliable UDP transport here, even though UDP itself is supported as a datagram mechanism.

Cadence adds a second kind of uncertainty. The release list shows v2.10.0 on July 3, 2026, v2.9.0 on June 11, 2025, and v2.8.0 on May 25, 2025, each named after an anime title. Roughly thirteen months separate the two most recent releases, so pinning buys stability for a while and then a long wait. The last push to the repository was July 9, 2026, and the default branch is dev rather than a release branch.

Every layer has a Windows twin, and the note says do not ship it

Each layer of the framework has a Windows counterpart at the top level of the repository. There is a windows file for the engine, the event loop, the listener, the acceptor, the connection, and the client, plus a windows test file, alongside one BSD specific connection file and one Linux specific connection file. The layout shows how much of this is platform conditional rather than portable in the usual Go sense.

The project is explicit about what the Windows build is for. A note in the feature list says the Windows version should only be used in development for developing and testing, and that it should not be used in production. That is stronger than a missing feature, because it covers the parts that do exist: connections, listeners, and clients are all implemented for Windows, and the maintainer still says not to ship them.

For a reader this settles the deployment question before any benchmarking. Linux, macOS, and the BSD family, named as Darwin, DragonFlyBSD, FreeBSD, NetBSD, and OpenBSD, are the targets the feature list treats as real. If a service must run on Windows in production, gnet is the wrong dependency no matter how the code compiles there, and no setting changes that.

The transport layer ends at TCP, UDP, and Unix sockets

The framework describes itself as working on the transport layer with TCP, UDP, and Unix Domain Socket. Everything above that line belongs to the application. HTTP, RPC, WebSocket, and Redis appear as examples of protocols you implement on top of gnet, and the framing is turned around on purpose: you get an HTTP server by implementing HTTP, and a Redis server by implementing the Redis protocol. Nothing in the framework parses those bytes for you.

This is presented as a position rather than an unfinished roadmap. The text argues that gnet and Go's net package do not share the same philosophy in network programming, that the two cannot be reconciled, and that gnet is meant as an alternative for performance critical services rather than a replacement for net. It also says the API set is deliberately small, limited to the core functionality a network application needs, and that there is no plan to become a coverall framework.

The consequence is operational rather than philosophical. Every protocol parser, every keepalive rule, and every header limit becomes code you own, write, and patch for security. For a team that already has a protocol implementation and wants a faster transport underneath it, that is a fair trade. For a team that wanted to swap the transport under an existing server, the work is the server itself.

Lock-free loops with an ants pool, and no stated boundary on blocking

Two of the stated milestones shape how code runs inside the framework: the event loop is high performance and driven by a networking model of multiple threads and goroutines, and the entire runtime is lock-free. The second claim matters more, because it removes the usual reason to reach for a mutex in connection handling and makes the concurrency story look simple from the outside.

Blocking work has a designated home. A built-in goroutine pool ships with the framework, powered by the ants library, which the module file requires at version 2.12.1. So the design anticipates work that cannot run inline and gives you a pool to move it onto.

Buffer choices are enumerated: an elastic ring buffer, a linked list buffer, and an elastic mixed buffer.

The first place ranking comes with one 28 core machine attached

The performance claim in the file is a placement on a leaderboard, and the placement comes with a machine attached. The hardware environment for the TechEmpower run is written out as a fixed configuration.

# Hardware Environment
* 28 HT Cores Intel(R) Xeon(R) Gold 5120 CPU @ 3.20GHz
* 32GB RAM
* Dedicated Cisco 10-gigabit Ethernet switch
* Debian 12 "bookworm"
* Go1.19.x linux/amd64

Then the claim: a leaderboard of the top 50 out of 486 frameworks spanning programming languages worldwide, in which gnet is ranked first. Read precisely, that is one framework's rank on one benchmark run, under the hardware above.

The ranking cannot be turned into a capacity estimate for your own service, and the introduction claims higher performance with lower memory consumption than net in many specific scenarios. The scope is doing the work there, and the scenarios are not named. There is also a version mismatch worth noticing: the benchmark ran on Go 1.19.x while the module file now declares go 1.20, so the published result came from a toolchain older than the minimum the module requires.

Two reactors, two connection containers, and an options file nobody documents

Underneath the documented API sit implementation files such as two reactor files at the root, one named default and one named ultimate. Two connection containers appear the same way, a map and a matrix, and only one of the two, the matrix, has a dedicated test file at the root. Whether that reflects a preference for new code, a deprecation, or a gap in coverage cannot be told from outside the repository.

The options file at the root is the more consequential omission for anyone tuning a service. Its presence says a configuration surface exists. A separate load balancer file backs the three named algorithms, Round-Robin, Source-Addr-Hash, and Least-Connections, and a client file sits behind the gnet client milestone alongside ticker support and the ability to register new connections to event-loops.

pkg.go.dev is linked for API reference. Anyone planning capacity work should budget reading options.go and both reactor files before writing the first handler.

Editorial conclusion

Pick gnet when a service is transport bound, you already control the protocol above TCP or UDP, and it will run on Linux or a BSD. Do not pick it to terminate TLS, to pick up io_uring or KCP, or to ship on Windows. Before committing, read options.go and the reactor files, and note that the last push was July 9, 2026 against v2.10.0 from July 3, 2026.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. panjf2000/gnet on GitHub
3. Project website
4. README
5. Releases