music21

9.9.1 · active · verified Fri Apr 17

music21 is a Toolkit for Computer-Aided Musical Analysis and Computational Musicology. It provides objects and methods to represent musical notation and analytical concepts, allowing for programmatic manipulation, analysis, and generation of musical data. Version 9.9.1 is the latest release, with a frequent release cadence, often addressing Python compatibility and adding new features for import/export.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'musescore' (or 'lilypond', 'finale')
```
cause 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.

fix Install 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'
```
cause 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.

fix Correct 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)
```
cause An incompatibility in `music21` v9.9.0 with Python 3.14's handling of `NotImplemented` caused specific functions to fail.

fix Upgrade `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)
```
cause An older version of `music21` is incompatible with `numpy` 2.0 or newer, leading to runtime errors when `music21` tries to use `numpy` functionalities.

fix Upgrade `music21` to version 9.7.1 or newer: `pip install -U music21`. Version 9.7.1 explicitly added support for `numpy` 2.0.

Warnings

breaking Version 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.
Fix: Review 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.
gotcha The `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.
Fix: Install 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.
gotcha Older 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.
Fix: Ensure `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`.
gotcha Python 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.
Fix: Upgrade `music21` to v9.9.1 or newer: `pip install -U music21`. Users not on Python 3.14 are not affected.
gotcha Small, 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.
Fix: Review calls to affected methods, particularly those involving `interval` objects, and adjust arguments or return value handling if unexpected typing errors or behavior changes occur.

Install

pip install music21 Install stable version

Imports

Stream
```
from music21.stream import Stream
```
Note
wrong:
```
from music21 import note
```
correct:
```
from music21.note 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
```

Quickstart

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')")

view raw JSON →