Skip to content


Repository files navigation



MQTT is a protocol for message queueing over a network. This project provides a client library for the Go programming language. Message-delivery guarantees are maintained at all costs, even when in error. The client recovers from failure with automatic reconnects. Message transfers in both directions do zero-copy.

The development was kindly sponsored by Northvolt as a gift to the open-source community. Many navigated over unreliable connections since then.

This is free and unencumbered software released into the public domain.

Go Reference Build Status


Client instantiation validates the configuration only. Network management itself operates from the read routine.

client, err := mqtt.VolatileSession("demo-client", &mqtt.Config{
	Dialer:       mqtt.NewDialer("tcp", ""),
	PauseTimeout: 4 * time.Second,
	CleanSession: true,
if err != nil {
	log.Fatal("exit on broken setup: ", err)

A read routine sees inbound messages from any of the subscribed topics.

for {
	message, topic, err := client.ReadSlices()
	switch {
	case err == nil:
		r, _ := utf8.DecodeLastRune(message)
		switch r {
		case '', '':
			log.Printf("%qat %q", message, topic)

	case errors.Is(err, mqtt.ErrClosed):
		return // client terminated

		log.Print("broker unavailable: ", err)
		time.Sleep(time.Second) // backoff

The client supports confirmed message delivery with full progress disclosure. Message transfers without confirmation can be as simple as the following.

err := client.Publish(ctx.Done(), []byte("20.8"), "bedroom")
if err != nil {
	log.Print("thermostat update lost: ", err)

See the examples from the package documentation for more detail.

Command-Line Client

Run go install to build the binary.

	mqttc  MQTT broker access

	mqttc [options] address

	The command connects to the address argument, with an option to
	publish a message and/or subscribe with topic filters.

	When the address does not specify a port, then the defaults are
	applied, which is 1883 for plain connections and 8883 for TLS.

  -ca file
    	Amend the trusted certificate authorities with a PEM file.
  -cert file
    	Use a client certificate from a PEM file (with a corresponding
    	-key option).
  -client identifier
    	Use a specific client identifier. (default "generated")
  -key file
    	Use a private key (matching the client certificate) from a PEM
  -net name
    	Select the network by name. Valid alternatives include tcp4,
    	tcp6 and unix. (default "tcp")
  -pass file
    	The file content is used as a password.
  -prefix string
    	Print a string before each inbound message.
  -publish topic
    	Send a message to a topic. The payload is read from standard
    	Suppress all output to standard error. Error reporting is
    	deduced to the exit code only.
    	Print inbound topics and messages as quoted strings.
  -server name
    	Use a specific server name with TLS
  -subscribe filter
    	Listen with a topic filter. Inbound messages are printed to
    	standard output until interrupted by a signal(3). Multiple
    	-subscribe options may be applied together.
  -suffix string
    	Print a string after each inbound message. (default "\n")
  -timeout duration
    	Network operation expiry. (default 4s)
    	Secure the connection with TLS.
    	Print the respective topic of each inbound message.
  -user name
    	The user name may be used by the broker for authentication
    	and/or authorization purposes.
    	Produces more output to standard error for debug purposes.

	(0) no error
	(1) MQTT operational error
	(2) illegal command invocation
	(5) connection refused: unacceptable protocol version
	(6) connection refused: identifier rejected
	(7) connection refused: server unavailable
	(8) connection refused: bad username or password
	(9) connection refused: not authorized
	(130) close on SIGINT
	(143) disconnect on SIGTERM

	Send a message:

		echo "hello" | mqttc -publish chat/misc localhost

	Print messages:

		mqttc -subscribe "news/#" -prefix " " :1883

	Health check:

		mqttc -tls || echo "exit $?"

	Report bugs at <>.


Standard Compliance

The implementation follows version 3.1.1 of the OASIS specification in a strict manner. Support for the original IBM-specification may be added at some point in time.

There are no plans to support protocol version 5. Version 3 is lean and well suited for IOT. The additions in version 5 may be more of a fit for backend computing.

See the Broker wiki for implementation specifics, especially the AWS IoT users.