{"id":9964,"library":"music21","title":"music21","description":"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.","status":"active","version":"9.9.1","language":"en","source_language":"en","source_url":"https://github.com/cuthbertLab/music21","tags":["music","musicology","audio","analysis","notation","midi","musicxml","score"],"install":[{"cmd":"pip install music21","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for numerical operations and data structures within music21. Required for various functionalities.","package":"numpy","optional":false}],"imports":[{"symbol":"Stream","correct":"from music21.stream import Stream"},{"note":"Commonly, users try to import 'note' directly from 'music21' instead of 'music21.note.Note' or 'from music21 import note'.","wrong":"from music21 import note","symbol":"Note","correct":"from music21.note import Note"},{"symbol":"converter","correct":"from music21 import converter"},{"symbol":"environment","correct":"from music21 import environment"}],"quickstart":{"code":"import music21\nfrom music21 import note, stream, tempo\n\n# Create a musical stream (like a score or a part)\ns = stream.Stream()\ns.append(tempo.MetronomeMark(number=120))\n\n# Add some notes\nn1 = note.Note('C4')\nn1.duration.type = 'quarter'\ns.append(n1)\n\nn2 = note.Note('D4')\nn2.duration.type = 'quarter'\ns.append(n2)\n\nn3 = note.Note('E4')\nn3.duration.type = 'half'\ns.append(n3)\n\n# Display the stream (requires an external MusicXML viewer like MuseScore)\n# If no viewer is installed, this might open a browser with an XML file or fail.\n# For headless environments, consider s.write('midi') or s.write('musicxml').\ntry:\n    s.show()\nexcept Exception as e:\n    print(f\"Could not display score: {e}\")\n    print(\"Try installing MuseScore or using s.write('musicxml', fp='my_score.xml')\")\n","lang":"python","description":"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)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"9.x.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<9.7.1"},{"fix":"Upgrade `music21` to v9.9.1 or newer: `pip install -U music21`. Users not on Python 3.14 are not affected.","message":"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.","severity":"gotcha","affected_versions":"9.9.0 with Python 3.14"},{"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.","message":"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.","severity":"gotcha","affected_versions":"9.5.0 and later"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'musescore' (or 'lilypond', 'finale')"},{"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.","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.","error":"AttributeError: module 'music21' has no attribute 'note'"},{"fix":"Upgrade `music21` to version 9.9.1 or newer: `pip install -U music21`. This issue was patched in v9.9.1.","cause":"An incompatibility in `music21` v9.9.0 with Python 3.14's handling of `NotImplemented` caused specific functions to fail.","error":"TypeError: 'NotImplemented' object is not callable (when running with Python 3.14)"},{"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.","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.","error":"ImportError: numpy.core.multiarray failed to import (or similar numpy-related errors)"}]}