cloudwego/hertz: a Go HTTP framework for microservices that need Netpoll and layered extension

The problem Hertz targets: Go microservices that outgrow the standard HTTP server

The README is blunt about the origin story. Hertz was originally a fork of fasthttp, inspired by gin and echo, and combined with internal requirements at ByteDance, where the README says it is widely used. That combination explains most of its design choices. A team that starts on net/http eventually wants a different network layer, a custom protocol parser, or a logger that matches an internal tracing system. Retrofitting those onto the standard library is awkward because the server, the connection handling and the request context are not designed as separate layers.

Hertz answers that by splitting the stack. Netpoll, a network library from the same organisation, is the default, and the README states that in some special scenarios Hertz has advantages in QPS and time delay compared to Go Net. Note the wording: some special scenarios, not all. The benchmark project, hertz-benchmark, is where the project says those numbers live, and the README itself warns that performance testing can only provide a relative reference because production has many influencing factors.

The audience is narrow on purpose. This is for teams building microservices in Go who care about the network layer and who expect to customise it. If you are writing a small internal service with a handful of routes, the extra machinery buys you very little.

Layered design, Netpoll by default, and switching back to Go Net

The architecture is described as layered, with more interfaces and default extension implementations than a typical router. Two consequences follow from that.

First, the network layer is swappable. The README lists network layer switching capability as a basic feature: users can choose between Netpoll and Go Net on demand, and the network library itself can be extended as a plug-in. That matters when a deployment environment interacts badly with Netpoll, or when a team wants to reuse an existing connection pool. The switch is a configuration decision rather than a rewrite.

Second, protocol handling is layered too. Hertz provides HTTP/1.1 and ALPN natively, and the README states that custom build protocol resolution logic is possible because of the layering. HTTP/2 and WebSocket are not in the core repository. They are listed among the hertz-contrib extensions, alongside Autotls for Let's Encrypt, Etag, and a bbr-based Limiter. That split is worth understanding before you plan: the core stays small, and the community maintains the rest.

The dependency list in go.mod reflects how much of the request path is owned by the project. Netpoll, sonic for JSON, gopkg, base64x and gjson are all direct requirements. That is a heavier dependency footprint than a router that only wraps net/http, and it is the price of the layered approach.

Installing Hertz and writing a first server

The README points to the Getting Started page on cloudwego.io for setup, and the hertz-examples repository for code out of the box. The module path is github.com/cloudwego/hertz, and go.mod declares go 1.20, so the toolchain needs to be at least that version. The repository's Makefile shows how the project itself is fetched and checked, which is the closest thing to an install recipe in the files:

go get golang.org/x/lint/golint

That target is part of the project's own tooling rather than an application dependency. For an application, add the module by its path, github.com/cloudwego/hertz, and check the Getting Started page for the current fetch command. The repository carries runnable programs under examples/, including examples/html_rendering and examples/standard, and hertz-examples is the recommended place for complete programs rather than isolated snippets.

One detail is documented and worth repeating before you write a handler: the README describes Hertz as providing HTTP/1.1 and ALPN natively, and the framework's own request context is the second argument in a handler, with the standard context first. That ordering is the detail most likely to trip up anyone porting routes from gin or echo. The README does not document a default listening port, so check the reference section for configurable items before you hardcode anything.

Where Hertz is the wrong choice

The framework's own README makes an admission that is easy to skim past: at present, only stable capabilities are open-sourced to the community, with more planning described in ROADMAP.md. Read that as a statement about surface area. If a capability you need is not in that stable set, you are not looking at a configuration flag. You are either waiting, or writing the extension yourself against the layered interfaces.

The second constraint is the extension split. HTTP/2, WebSocket, Autotls, Etag and the limiter are hertz-contrib packages, which the README describes as built and maintained by the community. A community-maintained extension has a different release cadence and a different support expectation than the core module. Teams that require a single vendor accountable for the whole stack should weigh that.

The third is the fork lineage. Hertz descends from fasthttp, and its handler signature is not the net/http signature. Any middleware, instrumentation or third-party library written against http.Handler will not drop in. Porting cost is real, and it is paid once per codebase, not once per route.

Finally, the performance claim is deliberately hedged. The README says advantages appear in some special scenarios and points to a separate benchmark repository. If raw throughput is the only reason you are considering Hertz, the honest first step is to read that benchmark project and reproduce it against your own workload, because the project itself declines to make a general claim.

Hertz compared with gin and echo

The README names gin and echo as inspirations, which makes the comparison fair game. The difference is not the routing API, which is close enough that a route registered in either style will look familiar. The difference is what sits underneath the router.

Gin and echo are built on net/http. Their request context wraps the standard library's, and the connection handling is whatever the Go runtime provides. That is why the middleware ecosystem is so large: everything written for net/http is compatible. Hertz replaces that foundation with Netpoll by default and exposes the network layer as a switchable component. The benefit is control over connection handling and the option of a different network library. The cost is the ecosystem compatibility described above.

Echo also leans toward batteries included, with middleware shipped in the main project. Hertz pushes HTTP/2, WebSocket and TLS automation out to hertz-contrib. Neither approach is wrong, but they fail differently. With echo, you get a larger core surface and fewer decisions. With Hertz, the core stays small and you assemble the rest, which is more work up front and more control later.

One more distinction worth stating plainly: Hertz is not a general-purpose web framework for content sites. It is aimed at microservices, and the README frames the choice in terms of microservice performance and internal customisation requirements.

Licence, releases and the cost of staying current

Hertz is licensed under Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. Apache-2.0 permits commercial use and modification, and it includes a patent grant. The NOTICE file is the part teams forget: if you redistribute the software, Apache-2.0 requires you to preserve attribution notices. This is not legal advice, and organisations with a formal open source review process should run it through that process rather than treating a licence identifier as sufficient.

The release cadence is visible in the tags. v0.10.6 was published on 2026-08-06, v0.10.5 on 2026-06-11, and v0.10.4 on 2026-01-26. The last push to the repository was on 2026-08-26. The project is not archived. The version numbers are still in the 0.x range, which is a signal about API stability expectations rather than a defect, but it is the kind of thing to check before pinning a dependency across a large service fleet.

Upgrade cost is dominated by the extension split rather than the core. If you use only the core module, an upgrade is a go.mod bump and a test run. If you depend on hertz-contrib packages, each of those moves on its own schedule, and a core upgrade can leave you waiting on an extension. The Makefile targets are worth knowing for contributors: make vet runs go vet, make lint runs golint after fetching it, and make fmt installs gofumpt and rewrites the tree with the -extra flag. Those targets are for working on Hertz itself, not for applications built with it.

Editorial conclusion

Adopt Hertz when you are writing Go microservices, want Netpoll as the default network layer, and expect to plug in your own protocol or network library later. Skip it when a standard net/http server is enough, or when you depend on middleware that only exists for the standard library. Before committing, check which hertz-contrib extension you actually need, confirm the Apache-2.0 licence and NOTICE file meet your distribution policy, and read the ROADMAP.md note that only stable capabilities are open-sourced to the community.

Frequently asked questions

Official sources

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