Skip to content
Get packs

Guide · Open source

How to use sarama: a Go client library for Apache Kafka

Updated · written with AI from the project's own documentation and checked against our catalogue data

Sarama is an open-source Go library that lets Go programs send and receive messages on Apache Kafka, a system for passing streams of messages between programs. This guide explains what sarama does, how to get started with it, where its documentation and test mocks live, and how it compares with other Go Kafka clients. It is written for developers who already know some Go and want to decide whether sarama fits their service.

saramaIBM/sarama · ★ 12.5k · MIT

Quick start

  1. 1Confirm Go is installed. Sarama is a Go library, so make sure Go is available and your project uses Go modules.
  2. 2Get the source. The README's install step clones the repository with git clone https://github.com/IBM/sarama.
  3. 3Read the API docs. Open pkg.go.dev/github.com/IBM/sarama to find the producer and consumer APIs and examples.
  4. 4Look at the examples. Review the examples directory for more elaborate sample applications.
  5. 5Import sarama into your code. Add sarama to your Go module and use it to produce or consume Kafka messages from your service.
  6. 6Write tests with mocks. Use the mocks subpackage to test code that depends on Kafka without a live broker.

What sarama is and what it does not do

Sarama is an MIT-licensed Go client library for Apache Kafka. You import it into your Go code, and your code uses it to produce messages to Kafka and consume messages from Kafka.

Sarama is a client only. It does not run Kafka itself, so you still need a Kafka cluster somewhere, either one you operate or a managed service.

  • Use it from Go services that need to send or receive Kafka messages.
  • Do not use it for non-Go projects; the README covers only Go.
  • Do not expect it to provision or host a Kafka broker.

Install sarama and check your Go setup

Sarama is a Go library, so you need Go installed. The README excerpt does not state a minimum Go version, so check the package documentation for current requirements. The README's install step begins by cloning the repository.

Sarama is consumed as a Go module, so your project should be set up with Go modules before you import it.

  • Prerequisite: Go (the README excerpt does not specify a version).
  • The README shows cloning the repository with git.
git clone https://github.com/IBM/sarama

Find the API documentation and examples

The README points to pkg.go.dev for API documentation and examples. Start there to look up the functions and types you need before writing code.

The repository also includes an examples directory with more elaborate example applications, and a tools directory with command line tools for testing, diagnostics, and instrumentation.

  • API docs and examples: pkg.go.dev/github.com/IBM/sarama
  • Example applications: the examples directory in the repository
  • Command line tools: the tools directory in the repository
  • Frequently Asked Questions and design notes: the project wiki

Test Kafka-dependent code with the mocks subpackage

Sarama includes a mocks subpackage intended for testing. Use it when your own code depends on Kafka and you want to test that logic without a live broker.

The README only states that mocks are available in the mocks subpackage. Check the package documentation for how to set them up.

  • Location: the mocks subpackage in the repository.

Understand compatibility and versioning

Sarama states a "2 releases + 2 months" compatibility guarantee. It supports the two latest stable releases of Kafka and Go, and gives a two month grace period for older releases. The README adds that older Kafka releases are still likely to work.

Sarama follows semantic versioning and uses the standard Go module version numbering scheme for API stability. A changelog is kept in the repository.

  • Supports the two latest stable Kafka and Go releases.
  • Two month grace period for older releases.
  • Semantic versioning via Go module version numbers.
  • Changelog: CHANGELOG.md in the repository.

Compare sarama with other Go Kafka clients

Other Go Kafka clients often compared with sarama include confluent-kafka-go, franz-go, and kafka-go. The source does not benchmark these against each other, so compare them on the criteria that matter to your project, such as API style, licence, maintenance, and the Kafka features you need.

If you want a documented compatibility policy and test mocks in one open-source library, sarama is a reasonable candidate to evaluate.

  • confluent-kafka-go
  • franz-go
  • kafka-go

What people use it for

  • Sending events from a Go web service to a Kafka topic.
  • Consuming messages from Kafka in a Go background worker.
  • Testing Go code that depends on Kafka using the mocks subpackage.
  • Diagnosing Kafka connectivity with the command line tools in the tools directory.

Frequently asked questions

Is sarama free to use?

Yes. Sarama is released under the MIT licence, as stated in the README and project metadata. You can use it in open-source or commercial Go code under those terms, and you should read the licence file for the exact conditions.

What do I need to install sarama?

You need Go and a Go module setup. The README excerpt does not state a minimum Go version, so check the pkg.go.dev documentation for requirements. The README's install step clones the repository from GitHub.

Does sarama run Kafka for me?

No. Sarama is a client library that your Go code imports. You still need a running Kafka cluster, either self-hosted or from a managed service.

Can I use sarama with languages other than Go?

The source describes sarama only as a Go client library and does not cover other languages. If your project is not written in Go, look at a client built for your language.

What is the difference between sarama and confluent-kafka-go?

The source does not compare them in detail. Confluent-kafka-go is another Go Kafka client; compare the two on API style, licence, maintenance, and the Kafka features your project needs.

How do I test code that uses sarama?

Use the mocks subpackage, which the README lists for testing. It lets you test Kafka-dependent code without connecting to a live broker.

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

Sarama is a good fit for Go developers who need an MIT-licensed Kafka client with a documented compatibility policy and test mocks. It is not a fit for non-Go projects, teams that want a managed Kafka service, or beginners without Go experience.

Install options & downloads