How to Use AKHQ: The Beginner's Guide (First Install, the Connect-to-Cluster Lesson, Topic Browsing, and the Consumer-Lag Arc)

CodexFuse Team · 2026-11-07T06:47:52.389Z · 17 min read min read

How Do I Use AKHQ?

Learning how to use akhq takes seven moves: install it with Docker, point it at a cluster, open the dashboard, browse a topic, read its messages, check consumer lag, and lock down access with groups. AKHQ, previously known as KafkaHQ, is a Kafka GUI for Apache Kafka that manages topics, topic data, consumer groups, schema registry, connect, and more, in the words of its own repository description, and this akhq tutorial follows the official AKHQ documentation and the project release pages, with every fact checked as of November 2026 and pinned to the current release, 0.28.0. A kafka web ui gives developers a browser window onto a cluster instead of a terminal full of shell scripts, and AKHQ is the Kafka-UI lane opener in our data-streaming cluster.

CodexFuse offers no AKHQ tool, so this guide teaches the real program on your own machine, not a web version of it. No Facebook promotion applies to this guide. The container route is covered in our Docker beginner guide, which you should read first if Docker is new to you.

1. Install AKHQ with Docker and pin the 0.28.0 image.
2. Write one application.yml file with a single cluster connection.
3. Start AKHQ and open the dashboard at localhost:8080.
4. Browse a topic and read its messages in the topic browser.
5. Open a consumer group and read its lag per partition.
6. Wire the schema registry and Kafka Connect views.
7. Set groups and a JWT secret so access is more than UI-only.

What Is AKHQ, Exactly?

An akhq kafka ui is a web interface that sits in front of your Kafka brokers and turns cluster administration into clickable pages. It lists brokers, topics, consumer groups, schemas, and connectors in one dashboard, and it works with a modern Kafka cluster, version 1.0 and newer, according to the project README. The interface is a React application since release 0.15.0, and the old pre-React UI path was slated for removal in 0.16.0, so do not look for the old UI path in a current install.

The repository, tchiotludo/akhq on GitHub, was created on 9 September 2018, which makes it 2,981 days old, or 8.16 years, and it holds 3,873 stars against 802 forks as of 7 November 2026. That works out to 4.83 stars per fork, and the 281 open issues work out to 7.26 per 100 stars, although the open issues count includes pull requests, because the GitHub API counts the two together. The Docker Hub image has 31,860,452 pulls, and the last push landed on 6 November 2026, 1 day ago, so the project is actively maintained.

The 2026 release line ran from 0.27.0 on 20 March to 0.28.0 on 6 August, which is three releases in 139 days, or one every 69.5 days on average. The two gaps were 53 days between 0.27.0 and 0.27.1 and 86 days between 0.27.1 and 0.28.0, while the 0.27.0 release itself is 232 days old and 0.27.1 is 179 days old. A duplicate tag named akhq-0.28.0 appeared one minute after the 0.28.0 release, so it is the same release counted twice by the tag list, not a separate version.

How Do I Install AKHQ?

An akhq install starts with one of three routes, and Docker is the route this guide uses first. An akhq docker install starts with a single run command that maps port 8080 and mounts your config file, and the image tag should be pinned to 0.28.0 instead of floating on latest. The machine that runs the stack needs a stable home, and the guide to that machine is our what is VPS hosting page, which explains the server choice before you install anything on it.

docker run -d \
    -p 8080:8080 \
    -v /tmp/application.yml:/app/application.yml \
    tchiotludo/akhq:0.28.0

Check the install by opening http://localhost:8080, which shows the cluster picker when AKHQ starts cleanly. If the page does not load, check that port 8080 is free and that the config file path you mounted is absolute, because a relative path fails silently. The standalone JAR route needs Java 25, not Java 11, because the current installation page says Java 25 and older copies of the README still say Java 11.

How Do I Connect AKHQ to a Cluster?

AKHQ connects to a cluster through one config file, application.yml, which lives at /app/application.yml inside the container by default. The file names each cluster under akhq.connections, gives its broker address in properties.bootstrap.servers, and optionally adds a schema registry and a Kafka Connect list. The same config can also be passed as an environment variable named AKHQ_CONFIGURATION, which keeps secrets out of a mounted file when you prefer that route.

akhq:
  connections:
    docker-kafka-server:
      properties:
        bootstrap.servers: "kafka:9092"
      schema-registry:
        url: "http://schema-registry:8085"
      connect:
        - name: "connect"
          url: "http://connect:8083"

Two syntax details catch beginners: the connect entry is a list, not a map, so each entry starts with a dash and a name, and connection names allow letters, numbers, underscores, and dashes but not dots. The schema registry entry is a map with a url and a type, where confluent is the default and tibco is the other option. You can define several clusters in the same file, because AKHQ supports multiple clusters in one UI and lists each connection on its home page.

The official quick preview compose file runs AKHQ with KRaft Kafka, a Schema Registry on port 8085, Kafka Connect on port 8083, and ksqlDB on port 8088, all in one stack. This guide does not teach the ZooKeeper-based Kafka stack, because the official compose is KRaft-based and Kafka 4 removed ZooKeeper entirely, while the field-leading codestudy guide still teaches the old ZooKeeper compose. Download the official file, run docker compose pull and docker compose up, and open localhost:8080 when the services report healthy.

services:
  akhq:
    image: tchiotludo/akhq:0.28.0
    restart: unless-stopped
    environment:
      AKHQ_CONFIGURATION: |
        akhq:
          connections:
            docker-kafka-server:
              properties:
                bootstrap.servers: "kafka:9092"
              schema-registry:
                url: "http://schema-registry:8085"
              connect:
                - name: "connect"
                  url: "http://connect:8083"
    ports:
      - 8080:8080

How Do I Browse Topics in AKHQ?

A kafka topic browser is the screen you will open most, and in AKHQ it starts on the Topics page, which lists every topic with its partition count, replication factor, and size. Clicking a topic opens its detail view, where the Partitions tab shows the replica layout and the Messages tab shows the records themselves. The topic data view defaults to 50 records per page and the oldest first, and you can flip the sort to newest when you are hunting a fresh record.

The Messages tab decodes JSON, Avro, and Protobuf records when a schema registry is wired in, and it lets you filter by key, value, or timestamp instead of scrolling blindly. You can also produce a test message from the same screen, which is the fastest way to prove a producer path works without leaving the browser. Creating a topic is a form with a name, partition count, and replication factor, and AKHQ fills the defaults from akhq.topic.partition and akhq.topic.replication when you leave them blank.

How Do I Check Consumer Lag?

Consumer lag is the gap between the newest record in a partition and the last offset a consumer group has committed, and it is the number that tells you whether your consumers are keeping up. Open the Consumer Groups page, pick a group, and AKHQ shows the lag for each partition plus a combined total, with the member list and the assignment beside it. Calling consumer lag the first thing operators check is this guide's own framing, not a surveyed fact, but it is the screen operators open first when a pipeline looks stuck.

A lag of zero means the group is caught up, a small steady lag means it is keeping pace, and a lag that grows every minute means the consumer is falling behind or has stopped. When the lag grows, check whether the consumer process is running, then check the topic for a surge in traffic, because a dead consumer and a traffic spike need different fixes. AKHQ lets an admin reset or update a group's offsets from the same page, which is how you rewind a group after fixing a bad deploy, and the roles that allow that are UPDATE_OFFSET and DELETE_OFFSET.

AKHQ shows the current lag but does not page you when it grows, so pair it with alerting that watches the same numbers over time. The guide to that alerting layer is our Prometheus beginner guide, which covers the metrics side that AKHQ leaves out. The codestudy guide states that AKHQ has no built-in integration with other monitoring tools, and the monitoring endpoint in the README was not verified this run, so treat dashboards and alerts as a separate layer.

What Can I See in the Schema Registry and Connect Views?

The Schema Registry view lists every subject and version, lets you read a schema, and shows which topics use it, which is how you catch a breaking schema change before it reaches production. AKHQ supports the Confluent registry by default and the Tibco registry as the other type, and both can carry basic-auth credentials when the registry is protected. The Connect view lists your connectors, shows each connector's tasks and status, and lets you create, pause, resume, and delete connectors without touching the Connect REST API.

The same screen also reaches ksqlDB, where you can run streaming queries against the cluster from the browser instead of a separate client. Node and broker pages show the cluster configuration, the log directories, and the per-broker settings, which is where you verify a config change actually landed. ACLs have their own view too, so you can see who may produce or consume on each topic without running the Kafka ACL scripts by hand.

How Do I Run AKHQ in Kubernetes?

The Helm route starts with helm repo add akhq https://akhq.io/ followed by helm upgrade --install akhq akhq/akhq, which installs the chart with its default values. Configuration goes into the chart values, where the configuration block lands in a ConfigMap and the secrets block lands in a Secret, and both are merged at startup. The chart needs Kubernetes 1.14 or newer from chart version 0.1.1 onward, so check your cluster version before you install.

The guide to the cluster itself is our Kubernetes beginner guide, which covers the platform AKHQ runs on when Docker is not enough. A Kubernetes install also benefits from dashboards that show the deployment's health, and the guide to those dashboards is our Grafana beginner guide. The Red Hat deployment piece from July 2023 used AKHQ 0.24.0 on OpenShift with AMQ Streams, which shows the same Helm route working on a managed platform.

AKHQ vs Kafdrop: Which Kafka Web UI Should I Pick?

AKHQ vs kafdrop is the comparison most readers ask about, because the two are the best-known free Kafka web UIs and they aim at different jobs. A kafka web ui either shows you the cluster or lets you run it, and Kafdrop leans toward showing while AKHQ leans toward running. Kafdrop is the lighter tool with one environment variable to configure, while AKHQ needs a YAML file, and that setup gap is the whole trade in one sentence.

Kafdrop has 6,163 stars against AKHQ's 3,873, a gap of 2,290 stars, which makes Kafdrop 1.59 times as starred while AKHQ holds 62.8 percent of Kafdrop's count. Kafdrop is also the fresher release: 4.3.1 is 9 days old against 0.28.0 at 93 days old, a gap of 84 days. The AKHQ repository is the older project by 260 days, created 2,981 days ago against Kafdrop's 2,721 days, or 8.16 years against 7.45 years, and Kafdrop holds more stars than AKHQ despite being the younger project.

The honest frame is that Kafdrop is a quick read-only peek and AKHQ is a full management console, so pick Kafdrop when you want the fastest possible look at one cluster and AKHQ when you need Connect, schemas, offsets, and access control. Other free options exist, and the Conduktor roundup calls Kafbat UI the most feature-complete free open-source option while calling AKHQ a strong alternative, particularly for Java-based tooling. No measured speed benchmark exists for either tool, so do not choose on claimed performance, because no such numbers were verified this run.

What Are the Seven Mistakes Beginners Make with AKHQ?

Seven mistakes show up again and again in beginner setups, and each one has a one-line fix. The table below lists them in the order you are most likely to hit them.

Sources

The AKHQ repository on GitHub supplied the star, fork, and open-issue counts, the 2018 creation date, the 0.28.0 release date of 6 August 2026, and the rename line that AKHQ was previously known as KafkaHQ. The official documentation at akhq.io supplied the Docker run command, the compose quick preview, the standalone JAR route with Java 25, the Helm commands, and the full configuration reference. The Docker Hub page for tchiotludo/akhq supplied the pull count of 31,860,452 as of 7 November 2026.

The codestudy.net guide, published 14 October 2025 and 389 days old, supplied the field-leading beginner arc and the ZooKeeper compose this guide deliberately does not copy. The two Red Hat Developer pieces supplied the managed-Kafka deployment stories, with the December 2022 piece at 1,412 days old and last updated 437 days ago, and the July 2023 piece at 1,200 days old, last updated 1,145 days ago, using AKHQ 0.24.0. The Kafdrop repository supplied its 6,163 stars, its 4.3.1 release of 29 October 2026, and the feature list behind the comparison table.

The computed numbers in this guide were produced by running a Python script on the fetched dates and counts, and every age, gap, and ratio above comes from that run. No commands in this guide were executed in a live testbed, so every command shown is documented syntax from the official docs, not output from a terminal session. The release dates, star counts, and pull count were re-fetched live for this guide and may have moved since.

from datetime import date

today = date(2026, 11, 7)

def age(d):
    return (today - d).days

print("AKHQ repo age days:", age(date(2018, 9, 9)))
print("AKHQ repo age years:", round(age(date(2018, 9, 9)) / 365.25, 2))
print("AKHQ 0.28.0 age days:", age(date(2026, 8, 6)))
print("AKHQ 0.27.1 age days:", age(date(2026, 5, 12)))
print("AKHQ 0.27.0 age days:", age(date(2026, 3, 20)))
print("Gap 0.27.0 to 0.27.1 days:", (date(2026, 5, 12) - date(2026, 3, 20)).days)
print("Gap 0.27.1 to 0.28.0 days:", (date(2026, 8, 6) - date(2026, 5, 12)).days)
print("Span 0.27.0 to 0.28.0 days:", (date(2026, 8, 6) - date(2026, 3, 20)).days)
print("Average of the two gaps:", round(((date(2026, 5, 12) - date(2026, 3, 20)).days + (date(2026, 8, 6) - date(2026, 5, 12)).days) / 2, 1))
print("AKHQ stars per fork:", round(3873 / 802, 2))
print("AKHQ open issues per 100 stars:", round(281 / 3873 * 100, 2))
print("Kafdrop repo age days:", age(date(2019, 5, 27)))
print("Kafdrop repo age years:", round(age(date(2019, 5, 27)) / 365.25, 2))
print("Kafdrop 4.3.1 age days:", age(date(2026, 10, 29)))
print("Kafdrop 4.3.0 age days:", age(date(2026, 8, 31)))
print("Kafdrop stars per fork:", round(6163 / 897, 2))
print("Kafdrop open issues per 100 stars:", round(40 / 6163 * 100, 2))
print("Star gap Kafdrop minus AKHQ:", 6163 - 3873)
print("Kafdrop stars as multiple of AKHQ:", round(6163 / 3873, 2))
print("AKHQ stars as share of Kafdrop:", round(3873 / 6163 * 100, 1))
print("AKHQ repo older than Kafdrop by days:", age(date(2018, 9, 9)) - age(date(2019, 5, 27)))
print("codestudy guide age days:", age(date(2025, 10, 14)))
print("Red Hat piece A published age days:", age(date(2022, 12, 26)))
print("Red Hat piece A updated age days:", age(date(2025, 8, 27)))
print("Red Hat piece B published age days:", age(date(2023, 7, 26)))
print("Red Hat piece B updated age days:", age(date(2023, 9, 19)))
print("AKHQ 0.28.0 older than Kafdrop 4.3.1 by days:", age(date(2026, 8, 6)) - age(date(2026, 10, 29)))
print("Docker Hub pulls:", 31860452)

Frequently Asked Questions

Is AKHQ free?

Yes, AKHQ is free and open source under the Apache License 2.0, so you can run it without paying for a license. The Docker Hub image has more than 31.8 million pulls, which shows wide use, but the pull count is not a download count for the project itself. You still pay for the machine and the Kafka cluster it connects to, because AKHQ itself adds no license cost.

What is the difference between AKHQ and KafkaHQ?

There is no difference, because AKHQ is the current name and KafkaHQ is the previous name of the same project. The repository title reads AKHQ, previously known as KafkaHQ, and the repository topics still include kafkahq as a reminder. No rename date was verified for this guide, so do not trust any article that states one without a source.

Does AKHQ need ZooKeeper?

No, AKHQ never needed ZooKeeper, because it talks to Kafka brokers through the standard client protocol. The official quick preview runs Kafka in KRaft mode with no ZooKeeper service, and Kafka 4 removed ZooKeeper entirely. Older guides that include a ZooKeeper service are teaching a retired stack, so follow the official compose instead.

How do I see consumer lag in AKHQ?

Open the Consumer Groups page, pick a group, and read the lag shown for each partition plus the combined total. A lag of zero means the group is caught up, while a lag that grows every minute means the consumer is falling behind. Admins can reset or update offsets from the same page when a rewind is needed after a fix.

Is AKHQ better than Kafdrop?

It depends on the job, because Kafdrop is the faster peek at one cluster while AKHQ is the fuller console with Connect, schemas, offsets, and groups. Kafdrop has 6,163 stars against AKHQ's 3,873, and its latest release is 84 days fresher. Pick Kafdrop for a quick look and AKHQ when you need to manage the cluster, not just view it.