python-rtmidi

1.5.8 verified Fri May 01 auth: no python

Python bindings for the RtMidi C++ library, providing real-time MIDI input/output using Cython. Current version 1.5.8, updates irregularly.

pip install python-rtmidi

Common errors

error ImportError: libasound.so.2: cannot open shared object file: No such file or directory ↓

cause Linux wheel does not bundle ALSA libraries starting version 1.5.8.

fix

Install ALSA development libraries: sudo apt-get install libasound2-dev on Debian/Ubuntu.

error ModuleNotFoundError: No module named 'rtmidi' ↓

cause Package not installed or virtual environment not activated.

fix

Run pip install python-rtmidi and ensure you are in the correct environment.

error ImportError: cannot import name 'MidiIn' from 'rtmidi.midi' ↓

cause Using old import path from version <1.0.

fix

Use from rtmidi import MidiIn.

error ValueError: Port index out of range ↓

cause Port index exceeds number of available ports.

fix

Check number of ports with midi_in.get_ports() before opening.

Warnings

breaking In version 1.5.8, Linux wheels no longer bundle libasound. If ALSA is not installed, the module will fail to load. ↓

fix Install ALSA development libraries (e.g., libasound2-dev on Debian) or use system package manager.

gotcha MidiIn and MidiOut objects are not thread-safe. Do not call methods from multiple threads without external locking. ↓

fix Use threading.Lock or restrict calls to a single thread.

gotcha On macOS, the library defaults to CoreMIDI but can be built with JACK. Ensure you have the correct backend installed. ↓

fix Check your installation with `import rtmidi; print(rtmidi.get_api())`.

deprecated The `midiutils` module is deprecated and may be removed in a future version. ↓

fix Use `get_ports()` methods on MidiIn/MidiOut instead.

Install

pip install python-rtmidi[alsa]

Imports

MidiIn

wrong

from rtmidi.midi import MidiIn

correct

from rtmidi import MidiIn

Old import path from version <1.0

MidiOut

wrong

from rtmidi.midi import MidiOut

correct

from rtmidi import MidiOut

Old import path from version <1.0

Quickstart

Basic setup: list ports, open input, set callback.

from rtmidi import MidiIn, MidiOut

# List available ports
midi_in = MidiIn()
print('Input ports:', midi_in.get_ports())

midi_out = MidiOut()
print('Output ports:', midi_out.get_ports())

# Open first port and listen
if midi_in.get_ports():
    midi_in.open_port(0)
    # Callback example
    def callback(message, data):
        print(message)
    midi_in.set_callback(callback)
    import time
    time.sleep(2)
    midi_in.close_port()
else:
    print('No MIDI input ports found.')