# franz-go: A Pure Go Kafka Client Covering Every Protocol Feature

> franz-go is an Apache Kafka client library written entirely in Go, covering protocol versions from 0.8.0 through 4.4 and above. It provides full exactly-once semantics, all SASL authentication mechanisms, a high-level admin package, and a schema registry client, with no C bindings required.

**twmb/franz-go** — franz-go is a feature complete, pure Go library for Kafka from 0.8.0 through 4.4+. Producing, consuming, transacting, administrating, etc.

- Repository: https://github.com/twmb/franz-go
- Stars: 3,082 · Forks: 305
- Language: Go
- License: BSD-3-Clause
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/twmb-franz-go

## What franz-go Is and Who It Is For

franz-go is an Apache Kafka client library written in pure Go, with no wrapper around a C library and no CGo dependency. The library targets Go developers who need comprehensive Kafka client functionality without maintaining separate packages for producing, consuming, transactions, and administration.

The stated goal in the README is to support every Kafka feature from version 0.8.0 onward and to implement every client-facing Kafka Improvement Proposal (KIP). Compatible brokers include Apache Kafka, Redpanda, Confluent Platform, Microsoft Event Hubs, and Amazon MSK. Each has minor differences: Event Hubs, for example, does not support producing with compression, which requires passing kgo.ProducerBatchCompression(kgo.NoCompression) when connecting to that broker.

## Feature Coverage from Kafka 0.8.0 Through 4.4

The feature list in the README covers the full range of Kafka client capabilities. On the producer side: idempotent producers, transactional producers, and full exactly-once semantics (EOS). On the consumer side: simple (legacy) consumers and group consumers with eager balancers (roundrobin, range, sticky) and the cooperative-sticky balancer, plus rack-aware partition assignment (KIP-881), server-side balancing (KIP-848), and share group consumers for queue-style consumption (KIP-932).

All four compression codecs are supported (gzip, snappy, lz4, zstd), SSL/TLS is available through custom dialer options, and all SASL mechanisms are implemented: GSSAPI/Kerberos, PLAIN, SCRAM, and OAUTHBEARER. The library also includes a high-level admin package (kadm) and a schema registry client with a Serde convenience type for encoding and decoding.

By default, the client issues an ApiVersions request when connecting to each broker and uses the maximum supported request version that broker reports. For brokers older than Kafka 0.10.0, which predate the ApiVersions request, the MaxVersions option is required.

## Installing franz-go and Writing a First Client

The repository uses separate Go module tags for the main client, plugins, and sub-packages. The main Kafka client package is kgo, imported from github.com/twmb/franz-go/pkg/kgo. Install it with:

```bash
go get github.com/twmb/franz-go
```

To install a plugin, for example the zap logging plugin:

```bash
go get github.com/twmb/franz-go/plugin/kzap
```

To install the high-level admin package:

```bash
go get github.com/twmb/franz-go/pkg/kadm
```

The go.mod at the root of the repository requires Go 1.26.0. A go.mod require section that includes franz-go looks like this:

```go
require (
	github.com/twmb/franz-go v1.21.0
	github.com/twmb/franz-go/pkg/kmsg v1.13.1
)
```

The README shows a basic overview of producing and consuming. A single client can both produce and consume:

```go
seeds := []string{"localhost:9092"}
cl, err := kgo.NewClient(
	kgo.SeedBrokers(seeds...),
	kgo.ConsumerGroup("my-group-identifier"),
	kgo.ConsumeTopics("foo"),
)
if err != nil {
	panic(err)
}
defer cl.Close()
```

The examples/ directory in the repository contains complete programs for transactions, DLQ patterns, SASL authentication, schema registry usage, and testing with the built-in kfake broker.

## Exactly-Once Semantics and the Transaction Model

franz-go supports full exactly-once semantics, which requires both idempotent producers and transactional consumers working together. The docs/transactions.md file in the repository documents the design, including how the library handles safety in pre-KIP-447 Kafka clusters.

The idempotent producer guarantees that duplicate records are not written to a topic even if the producer retries after a network failure. The transactional producer extends this by grouping produce and consume operations into atomic transactions: either all succeed or none are committed. This is the foundation for building stream-processing pipelines that consume from one topic, transform, and produce to another topic without duplicates or data loss across failures.

The examples/transactions/ directory in the repository contains working code that demonstrates this flow.

## Topic Recreation Behavior and Other Constraints

The README documents a specific behavior that can surprise users: franz-go always produces to or consumes from the first instance of a topic. If a topic is deleted and recreated, and if the broker is modern enough to use topic IDs, the client will detect the recreation and refuse to produce to or consume from the new topic instance. The README notes this behavior and mentions that the client can be configured to handle it, but the truncated documentation does not include the specific configuration option.

Version pinning is handled through the MaxVersions option, which locks the client to a specific Kafka wire protocol version rather than negotiating the maximum supported version. This is necessary for brokers older than Kafka 0.10.0.

The go.mod file retracts v1.11.4 with the comment: "This version is actually a breaking change and requires a major version change." Anyone using automated dependency updates should verify that their tooling respects retracted versions.

## franz-go Versus confluent-kafka-go and sarama

Two other Go Kafka clients appear frequently in comparisons: confluent-kafka-go and sarama. confluent-kafka-go is the official Confluent client, but it is a CGo wrapper around librdkafka, a C library. This means builds require a C toolchain, CGo must be enabled, and cross-compilation to a different target OS or architecture requires a matching C cross-compiler. franz-go avoids all of this by being pure Go, which allows straightforward cross-compilation with the standard Go toolchain.

samara is a widely used pure Go Kafka client maintained under the IBM umbrella. It predates franz-go and has a large existing user base. The primary qualitative difference is scope: franz-go explicitly aims to support every client KIP and Kafka version from 0.8.0 forward, while sarama has a narrower feature roadmap and a different API design. Teams migrating from sarama to franz-go will find API differences in how connections, partitioners, and consumer groups are configured.

For Go teams starting a new Kafka project, franz-go's comprehensive KIP coverage and pure Go build model are practical advantages over both alternatives.

## Package Structure, Metrics Hooks, and License

The repository is organized as a Go multi-module project. The core client is in pkg/kgo. The admin package is in pkg/kadm. The raw protocol message types are in pkg/kmsg. Plugins live under plugin/ and are released as separate modules (for example plugin/kzap for zap logging integration, and plugin support for Prometheus metrics).

The hooks system is the mechanism for adding metrics and logging. The docs/metrics-and-logging.md file in the repository describes how to implement hooks and includes notes on latency tracking. Existing plugins cover Prometheus and zap; the plugin/ directory contains the available integrations.

The library is licensed under the BSD 3-Clause license. This is a permissive license with no copyleft requirements: linking franz-go into a commercial application does not require publishing source code. The last push to the repository was on 2026-09-27, and the CHANGELOG.md file tracks changes across versions. The testing.md file in the docs/ directory describes how to write tests for code that uses franz-go, including the use of the built-in kfake broker for unit tests without a real Kafka cluster.

## Conclusion

franz-go is the right choice for Go teams building Kafka-based systems who want a single library that covers the full protocol without C dependencies. The exactly-once semantics, full SASL support, and schema registry client reduce the number of third-party packages needed in a production setup. Teams targeting Kafka brokers older than 0.10.0 should read the kversions package documentation and use the MaxVersions option before writing any production code. Check the retracted versions in go.mod (v1.11.4 was a breaking change) before pinning a version.

## FAQ

### What is franz-go?

franz-go is a pure Go Apache Kafka client library that covers the full Kafka protocol from version 0.8.0 through 4.4 and above. It provides idempotent and transactional producers, consumer groups with multiple balancing strategies, all SASL authentication mechanisms, and a high-level admin package, without any C dependencies.

### How does franz-go compare to confluent-kafka-go?

confluent-kafka-go wraps the C library librdkafka and requires CGo, which adds C toolchain dependencies and complicates cross-compilation. franz-go is written entirely in Go and has no C bindings, making cross-compilation straightforward with the standard Go toolchain.

### Does franz-go support exactly-once semantics?

Yes. franz-go supports full exactly-once semantics through idempotent and transactional producers combined with transactional consumers. The docs/transactions.md file in the repository describes the design and safety guarantees.

## Sources

- [Issues](https://github.com/twmb/franz-go/issues)
- [License: BSD-3-Clause](https://github.com/twmb/franz-go/blob/master/LICENSE)
- [README](https://github.com/twmb/franz-go/blob/master/README.md)
- [twmb/franz-go on GitHub](https://github.com/twmb/franz-go)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/twmb-franz-go