How to Install Mosquitto MQTT Broker (Ubuntu, Debian, Windows, macOS)

Eclipse Mosquitto is the most widely used open-source MQTT broker: small, fast and available for practically every operating system. This tutorial shows how to install Mosquitto on Ubuntu, Debian, Windows and macOS, run it as a background service, verify it with the command-line clients and avoid the most common trap of Mosquitto 2.x — the broker silently refusing remote connections.

New to MQTT itself? Read what is MQTT first; if you would rather not install anything on the host, see running Mosquitto in Docker.

Install Mosquitto on Ubuntu and Debian

Mosquitto is in the default Ubuntu and Debian repositories. The broker and the CLI clients are separate packages, so install both:

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Distribution packages can lag behind upstream releases. If you need the newest version on Ubuntu, the Mosquitto project publishes a PPA:

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Check what you got:

mosquitto -h | head -n 1

Run Mosquitto as a systemd service

The Debian package registers a mosquitto systemd unit and usually starts it right away. Use the usual commands to manage it:

sudo systemctl enable --now mosquitto   # start now and at boot
sudo systemctl status mosquitto         # is it running?
sudo systemctl restart mosquitto        # after editing the config
journalctl -u mosquitto -f              # follow the logs

The main config file is /etc/mosquitto/mosquitto.conf. It includes every *.conf file in /etc/mosquitto/conf.d/, which is the cleanest place for your own settings.

Install Mosquitto on Windows

1. Download the Windows installer (64-bit .exe) from the official download page at mosquitto.org/download.
2. Run it. Keep the Service component selected if you want Mosquitto to run as a Windows service. The default install path is C:\Program Files\mosquitto.
3. Add that folder to your PATH so mosquitto_pub and mosquitto_sub work from any terminal.

Start the service from an administrator PowerShell or Command Prompt:

net start mosquitto
# or run in the foreground with verbose logging:
cd "C:\Program Files\mosquitto"
.\mosquitto.exe -c mosquitto.conf -v

Install Mosquitto on macOS

With Homebrew it is a one-liner, and Homebrew's service manager keeps it running in the background:

brew install mosquitto
brew services start mosquitto     # run as a background service
brew services info mosquitto      # check status

The config file lives under Homebrew's prefix: /opt/homebrew/etc/mosquitto/mosquitto.conf on Apple Silicon or /usr/local/etc/mosquitto/mosquitto.conf on Intel Macs. The clients are included in the same formula.

Verify the installation with mosquitto_sub and mosquitto_pub

Open two terminals on the machine running the broker. Subscribe in the first:

mosquitto_sub -h localhost -t 'test/#' -v

Publish from the second:

mosquitto_pub -h localhost -t 'test/hello' -m 'Mosquitto works'

Terminal 1 should print test/hello Mosquitto works. For the full set of flags, keep our mosquitto_pub and mosquitto_sub cheat sheet open.

The Mosquitto 2.x "local only mode" gotcha

The localhost test works, but a client on another machine gets connection refused. This is by design. Since version 2.0, if mosquitto.conf defines no listener, Mosquitto binds only to the loopback interface and logs something like:

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

Mosquitto 2.x also defaults to allow_anonymous false as soon as you define a listener. So opening the port is not enough — you must also decide how clients authenticate. Create a small config file:

listener 1883
allow_anonymous true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Restart the broker (sudo systemctl restart mosquitto) and the port is reachable from the network. Creating the password file and adding ACLs and TLS is covered step by step in securing Mosquitto. To build a config without memorising directives, use the mosquitto.conf generator.

Optional: enable WebSockets

Browser clients cannot use raw TCP. To test your broker from a web page, add a second listener with the WebSockets protocol (see MQTT over WebSockets and MQTT ports):

listener 9001
protocol websockets

Note that a page served over HTTPS can only open wss:// connections, so for a browser client on the public web you will also need TLS on that listener. Before you go that far, you can get a feel for MQTT against a public test broker in the browser:

Try it in the online MQTT client

Where Mosquitto keeps its files

Whatever the platform, run mosquitto -c <path-to-conf> -v in a terminal when something does not start: it prints configuration errors directly instead of hiding them in a service log. Stop the service first, or the foreground instance will fail because the port is already taken.

Troubleshooting a fresh install

For other CONNACK codes and timeouts, see the MQTT connection errors guide.

Next steps

• Lock it down with passwords, ACLs and TLS: Mosquitto authentication.
• Prefer containers? Run Mosquitto in Docker.
• Compare Mosquitto with other brokers in our broker directory.

Frequently asked questions