Install

This page covers installing OmniPython. For general mip, micropython -m mip, and mpremote mip usage, see the OmniPython MIP index.

System prerequisites (desktop)

The desktop backends need SDL2 from the system package manager before the Python packages are installed:

sudo apt update && sudo apt install libsdl2-dev python3-venv   # Debian / Ubuntu / WSL

Fedora uses SDL2-devel; macOS uses Homebrew’s sdl2. On Windows, install Python from python.org — pygame-ce (PGDisplay) is generally the easiest window backend there, and WSL supports the Linux workflow unchanged.

Headless CI should set SDL_VIDEODRIVER=dummy and SDL_AUDIODRIVER=dummy. For Linux without X11 or Wayland, install the board_configs/sdldisplay/linux_kms board config, which sets SDL_VIDEODRIVER=kmsdrm before SDL initializes; the host needs an SDL build with KMSDRM support, access to /dev/dri, and no competing DRM master.

Target

Selection

Use case

Normal desktop

X11 / Wayland default

Desktop session

KMS

SDL_VIDEODRIVER=kmsdrm

Direct scanout with no window manager

Headless CI

SDL_VIDEODRIVER=dummy

Automated tests

Desktop with pip

One command installs the complete desktop stack: all portable OmniPython components, the desktop board configuration, and the bundled utility modules.

python -m pip install \
  omnipython-desktop

omnipython-desktop depends on omnipython; no extra is required. Verify the board and utility entry points in a fresh environment:

python -m venv .venv
. .venv/bin/activate
python -m pip install \
  omnipython-desktop
python -c "import board_config, micropython, mip; print(board_config.__file__)"

Install only the portable libraries when no desktop board is wanted:

python -m pip install \
  omnipython

MicroPython hardware board

Bringing up a board for the first time? Bring up a board is the guide: what the firmware already has so you do not install it twice, how to let the board fetch its own files over Wi-Fi instead of feeding them down a serial line, and the handful of traps that look like broken hardware.

Board installers live in this repository. Select the matching directory and install it from GitHub; omip finds its omnipython dependency on the index:

import omip

omip.install("github:PyDevices/omnipython/board_configs/busdisplay/i80/t-display-s3")

Each board installer includes its board-specific Python display, touch, and peripheral drivers. It does not pull optional Python bus fallbacks when the firmware is expected to provide the hardware interface.

CircuitPython board

On CircuitPython, omip also finds Adafruit’s libraries, the ones circup installs, compiled for the board’s CircuitPython version:

import omip

omip.install("adafruit_display_text")

It brings what the library needs too. A name on both the OmniPython index and Adafruit’s bundle comes from the OmniPython index; pass index=omip.ADAFRUIT for Adafruit’s. The board can only write its own drive once boot.py has made it writable, and omip says how when it isn’t.

Desktop with MicroPython MIP

Get the micropython (or micropython.exe) interpreter binary, either by running ./bin/fetch_interpreters.sh from a omnipython checkout (downloads the latest release’s assets into bin/) or by downloading it directly from the OmniPython releases page. Then create a ready-to-use workspace in the default user library location:

# Linux / macOS
mkdir -p ~/.micropython && cd ~/.micropython
micropython -m mip install --target lib \
  --index https://lib.omnipython.org \
  github:PyDevices/omnipython/board_configs/desktop
REM Windows (cmd.exe)
mkdir "%USERPROFILE%\.micropython" && cd "%USERPROFILE%\.micropython"
micropython.exe -m mip install --target lib ^
  --index https://lib.omnipython.org ^
  github:PyDevices/omnipython/board_configs/desktop

The desktop raw-GitHub installer depends on the indexed omnipython-desktop package. Installing into an arbitrary directory instead works the same way:

micropython -m mip install \
  --index https://lib.omnipython.org \
  github:PyDevices/omnipython/board_configs/desktop

Use --target lib when installing into a workspace whose import path expects a lib/ directory. Add --no-mpy when the same tree must be readable by CircuitPython or CPython.

Freezing OmniPython into one binary

If you want a single micropython.exe (or board image) that runs with nothing installed, freeze OmniPython into it with omnipython-builds’ build.py. Its omnipython variant also freezes the universal desktop board config:

build.py --port windows --variant omnipython --modules omnipython,<your app>

manifest.py freezes everything in lib/; board_configs/desktop/manifest.py freezes the desktop board config and the pure-Python SDL2 and Win32 bindings. A board_config.py beside your script still wins over the frozen one. For a board image, freeze lib/ only and install the board’s own config.

Frozen modules come before lib on sys.path, so a frozen OmniPython shadows any copy installed with mip, and updating it means rebuilding. The board’s root comes before them, though, so one module can be replaced without a rebuild by installing it there. That’s how to get a newer omip onto firmware that has one frozen in:

import mip

mip.install("github:PyDevices/omnipython/lib/omip.py", target="/")

From then on import omip finds the copy in the root. Asking a frozen omip to install itself skips it, since the copy it would put in lib would never run.

The same goes for a Python package that stands in for a module some firmware builds in. pygraphics is one: boards whose firmware has the C module skip the Python package, and omip.install("pygraphics") says so, while a board without it gets the package. Pass force=True to install it anyway.

Connected-device installation

mpremote can perform the same hardware-board install without running mip on the device:

mpremote mip install \
  --index https://lib.omnipython.org \
  github:PyDevices/omnipython/board_configs/busdisplay/i80/t-display-s3

The recommended hosted-interpreter search paths keep frozen firmware modules ahead of workspace fallbacks:

export MICROPYPATH=".:.frozen:lib:utils:~/.micropython/lib:/usr/lib/micropython"
export PYTHONPATH=".:lib:utils"
REM Windows (cmd.exe)
set MICROPYPATH=.;.frozen;lib;utils;%USERPROFILE%\.micropython\lib
set PYTHONPATH=.;lib;utils

This keeps the unix port’s default search order — .frozen, then ~/.micropython/lib, then /usr/lib/micropython — and adds ., lib/ and utils/ so a workspace runs from any directory. It is also why installing the CPython micropython.py compatibility module is harmless on MicroPython: .frozen resolves first.