Install & Compatibility
Where this runs
tested against v0.2.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.378s · 98.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.4s · import 0.382s · 95MB
98MB installed
● package 98MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PrettyMIDI
✓ from pretty_midi import PrettyMIDI
Instrument
✓ from pretty_midi import Instrument
Note
✓ from pretty_midi import Note
Create a simple MIDI file with a piano note (C4).
import pretty_midi
# Create a MIDI file
midi = pretty_midi.PrettyMIDI()
piano = pretty_midi.Instrument(program=0) # Acoustic Grand Piano
# Add a note (C4, start=0, end=1, velocity=100)
note = pretty_midi.Note(velocity=100, pitch=60, start=0, end=1)
piano.notes.append(note)
midi.instruments.append(piano)
midi.write('example.mid')
print('MIDI file created.')
Debug
Known issues
breakingnumpy integer aliases removed in numpy 1.24+; use np.int32 directly.fixUpdate to pretty-midi >=0.2.10.
affects: pretty-midi <=0.2.9 with numpy >=1.20
gotchaInstrument(...) with default program (0) creates an acoustic grand piano; for drums, set program=0 and is_drum=True.fixUse Instrument(program=0, is_drum=True) for drum tracks.
affects: all
gotchaNote start and end times are in seconds, not beats. Use MIDI tick conversion manually.fixAlways use seconds for note times; for beat-based timing, convert using tempo.
affects: all
deprecatedBackend 'pretty_midi.midi_processor' was deprecated and replaced by 'mido'. Old code using 'from pretty_midi.midi_processor import ...' will fail.fixInstall mido and let pretty_midi use it as backend automatically.
affects: >=0.2.6
Errors
Common errors & fixes
AttributeError: module 'pretty_midi' has no attribute 'midi_processor'
The old midi_processor module was removed; mido is now required.
fixInstall mido: pip install mido
AttributeError: module 'numpy' has no attribute 'int'
numpy 1.24+ removed np.int; use np.int32.
fixUpdate pretty-midi to 0.2.10 or later, or downgrade numpy.
TypeError: 'Note' object does not support item assignment
Trying to access notes like a list or dict instead of using the 'notes' attribute.
fixUse instrument.notes[index] to access notes, e.g., instrument.notes[0].
ValueError: Unknown key signature number -1
Key signature numbers must be in range -7 to 7. Check key signatures.
fixEnsure key signature numbers are between -7 (7 flats) and 7 (7 sharps).
Upgrade
Version history
0.2.11latest on PyPI · released Oct 8, 2025
Audit
Dependencies
numpyrequiredRequired for internal arrays and operations.
midorequiredRequired for MIDI file I/O (default backend).
scipyoptionalRequired for signal processing functions (e.g., piano roll).