Preview build — page text is a draft awaiting human review. Code badges come from real compiles. The flasher is real but not yet hardware-tested; the Playground is still a preview.
Get Started
MicroPython · MQTT

Fix MicroPython “ImportError: no module named 'umqtt'”

umqtt.simple is not part of every MicroPython build. Install it on the board with mip (or Thonny’s package manager) and keep the umqtt/ folder on the board.

Raspberry Pi Pico WPico 2 WESP32ESP8266Updated 3 Nov 2026

Community draft — report a mistake

What you see

OutputOutput
MicroPython v1.24.1 on 2024-11-29; Raspberry Pi Pico W with RP2040
Type "help()" for more information.
>>> %Run -c $EDITOR_CONTENT
Traceback (most recent call last):
  File "<stdin>", line 3, in <module>
ImportError: no module named 'umqtt'

ImportError: no module named 'umqtt' means the MQTT client library is not on the board. Unlike Arduino, MicroPython libraries are plain .py files that have to sit in the board’s own flash, normally under /lib.

Once Wi-Fi is up, install it from the REPL:

import network, time, mip
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("your-wifi", "your-password")
while not wlan.isconnected():
    time.sleep(0.5)
mip.install("umqtt.simple")

Then from umqtt.simple import MQTTClient works, and keeps working after a reset because the files stay in /lib/umqtt/.

Quick fix — try in order

  1. 1

    Check what the firmware already has

    In the REPL run help('modules'). If umqtt/simple is not in the list, the library has to be copied to the board — pip install on your PC does nothing for the board.

  2. 2

    Install it on the board with mip (needs Wi-Fi)

    Connect to Wi-Fi in the REPL, then run import mip; mip.install('umqtt.simple'). It downloads into /lib/umqtt/ on the board. Add mip.install('umqtt.robust') if your code imports robust.

  3. 3

    Or install from the PC

    With mpremote: mpremote mip install umqtt.simple. In Thonny: Tools → Manage packages → search umqtt.simple → Install (the board must be the selected interpreter, bottom-right).

  4. 4

    Import it with the full name

    Use from umqtt.simple import MQTTClient. import umqtt on its own gives you an empty package.

  5. 5

    Very old firmware? Update it

    Builds older than v1.20 have upip instead of mip. Flashing a current UF2/bin from micropython.org is easier than fighting upip.

Why it happens

Why does a tutorial import it without installing anything?

Some MicroPython builds bundle umqtt and others don’t, and that has changed between releases. A tutorial written on one board/firmware may not match yours. help('modules') shows the truth for your board.

I installed it with pip on my laptop

pip installs into the PC’s Python. MicroPython runs on the board, which only sees files in its own flash (/ and /lib).

It worked yesterday, now ImportError again

Re-flashing firmware or flash_nuke.uf2 wipes /lib. Re-install after every full erase.

mip.install fails with OSError -2 or -202

The board is not online or DNS failed. Connect Wi-Fi first — see OSError -202.

Board-specific notes

Raspberry Pi Pico (no W): No Wi-Fi chip, so no MQTT over Wi-Fi at all. You need a Pico W / Pico 2 W, or an ESP32.

ESP8266: Only about 40 KB of free RAM. Use umqtt.simple (not robust) and keep messages short.

Pico W: See the Pico W board page for the right UF2 — the plain Pico UF2 has no network module.

↑↓ to move · Enter to open