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 |
|
Direct scanout with no window manager |
Headless CI |
|
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.