Install & Compatibility
Where this runs
tested against v9.9.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.575s · 295.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.3s · import 1.422s · 289MB
302MB installed
● package 302MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Stream
✓ from music21.stream import Stream
Note
✓ from music21.note import Note
✗ from music21 import note
Commonly, users try to import 'note' directly from 'music21' instead of 'music21.note.Note' or 'from music21 import note'.
converter
✓ from music21 import converter
environment
✓ from music21 import environment
This quickstart demonstrates creating a simple musical stream with a few notes and displaying it. The `s.show()` method relies on external applications like MuseScore or LilyPond to render scores. Ensure you have one installed and configured for optimal results. Alternatively, you can save the output to a file (e.g., MusicXML or MIDI).
import music21
from music21 import note, stream, tempo
# Create a musical stream (like a score or a part)
s = stream.Stream()
s.append(tempo.MetronomeMark(number=120))
# Add some notes
n1 = note.Note('C4')
n1.duration.type = 'quarter'
s.append(n1)
n2 = note.Note('D4')
n2.duration.type = 'quarter'
s.append(n2)
n3 = note.Note('E4')
n3.duration.type = 'half'
s.append(n3)
# Display the stream (requires an external MusicXML viewer like MuseScore)
# If no viewer is installed, this might open a browser with an XML file or fail.
# For headless environments, consider s.write('midi') or s.write('musicxml').
try:
s.show()
except Exception as e:
print(f"Could not display score: {e}")
print("Try installing MuseScore or using s.write('musicxml', fp='my_score.xml')")
Debug
Known issues
breakingVersion 9 introduced several non-backwards compatible changes from v8, affecting core APIs and requiring Python 3.10+ (v8 required 3.8+). Users upgrading from v7 or earlier will encounter significant API and Python version changes.fixReview the official music21 v9 release notes for specific breaking changes. Ensure your Python environment is 3.10 or newer. Adapt code to the new API patterns.
affects: 9.x.x
gotchaThe `music21.show()` method relies on external applications (e.g., MuseScore, LilyPond, Finale) for rendering scores. If these applications are not installed and configured, `show()` calls will fail with a `FileNotFoundError` or result in unhelpful output.fixInstall a compatible MusicXML viewer (e.g., MuseScore, free and open-source) and ensure its executable is in your system's PATH. Alternatively, use `stream.write('midi', fp='output.mid')` or `stream.write('musicxml', fp='output.xml')` to save files instead of displaying. affects: All
gotchaOlder versions of `music21` (specifically before v9.7.1) might have compatibility issues with `numpy` 2.0, leading to installation or runtime errors. This was a common issue when `numpy` released major updates.fixEnsure `music21` is updated to at least v9.7.1 or newer: `pip install -U music21`. If you must use an older `music21` version, pin `numpy<2.0`.
affects: <9.7.1
gotchaPython 3.14 users on `music21` v9.9.0 might encounter `TypeError: 'NotImplemented' object is not callable` errors due to a specific incompatibility. This was a transient issue.fixUpgrade `music21` to v9.9.1 or newer: `pip install -U music21`. Users not on Python 3.14 are not affected.
affects: 9.9.0 with Python 3.14
gotchaSmall, undocumented incompatibilities were introduced in v9.5.0 for methods like `interval.getWrittenLowerNote` to ensure correct typing. While not officially marked as breaking changes, code relying on the exact prior behavior of these specific methods might need minor adjustment.fixReview calls to affected methods, particularly those involving `interval` objects, and adjust arguments or return value handling if unexpected typing errors or behavior changes occur.
affects: 9.5.0 and later
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'musescore' (or 'lilypond', 'finale')
The `music21.stream.Stream.show()` method attempts to launch an external application (like MuseScore or LilyPond) to render the score, but the application is not installed or not found in the system's PATH.
fixInstall a compatible MusicXML viewer (e.g., MuseScore, LilyPond) and ensure its executable is accessible from your system's PATH. Alternatively, use `my_stream.write('musicxml', fp='output.xml')` or `my_stream.write('midi', fp='output.mid')` to save the output to a file. AttributeError: module 'music21' has no attribute 'note'
You are attempting to access a submodule (like `note`) directly from the top-level `music21` package when it should be imported explicitly or accessed via a specific path.
fixCorrect your import statement. For example, use `from music21 import note` to import the submodule, or `from music21.note import Note` to import a specific class.
TypeError: 'NotImplemented' object is not callable (when running with Python 3.14)
An incompatibility in `music21` v9.9.0 with Python 3.14's handling of `NotImplemented` caused specific functions to fail.
fixUpgrade `music21` to version 9.9.1 or newer: `pip install -U music21`. This issue was patched in v9.9.1.
ImportError: numpy.core.multiarray failed to import (or similar numpy-related errors)
An older version of `music21` is incompatible with `numpy` 2.0 or newer, leading to runtime errors when `music21` tries to use `numpy` functionalities.
fixUpgrade `music21` to version 9.7.1 or newer: `pip install -U music21`. Version 9.7.1 explicitly added support for `numpy` 2.0.
Upgrade
Version history
10.3.0latest on PyPI · released May 26, 2026
Audit
Dependencies
numpyrequiredUsed for numerical operations and data structures within music21. Required for various functionalities.