Registry /
database / pyobjc-framework-ituneslibrary
Install & Compatibility
Where this runs
tested against v? · pip install
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.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ITLibrary
✓ from iTunesLibrary import ITLibrary
The primary class for accessing the iTunes/Music library.
This quickstart demonstrates how to load the user's iTunes/Music library and print some basic information about it. It uses the `ITLibrary` class to access media items and playlists. Note the requirement for macOS 'Full Disk Access' to prevent permission errors.
import os
from iTunesLibrary import ITLibrary
def get_itunes_library_info():
"""
Retrieves and prints basic information from the user's Music library.
Requires 'Full Disk Access' for the Python application in macOS System Settings.
"""
try:
# API Version 1 is generally current for basic access
library = ITLibrary.libraryWithAPIVersion_error_(1, None)
if library:
print(f"Library Name: {library.applicationDisplayName()}")
print(f"Total Tracks: {len(library.allMediaItems())}")
print(f"Number of Playlists: {len(library.allPlaylists())}")
# Example: Iterate through first 3 tracks
print("\nFirst 3 Tracks:")
for i, item in enumerate(library.allMediaItems()):
if i >= 3:
break
title = item.title()
artist = item.artist().name() if item.artist() else "Unknown Artist"
album = item.album().title() if item.album() else "Unknown Album"
print(f"- Title: {title}, Artist: {artist}, Album: {album}")
# Get file path if available
if item.location():
file_path = os.fspath(item.location()) # Requires PyObjC 10.1+
# print(f" Path: {file_path}") # Uncomment to see paths
else:
print("Failed to load iTunes Library.")
except Exception as e:
print(f"An error occurred: {e}")
print("\nNote: Accessing the iTunes/Music Library typically requires 'Full Disk Access' for your Python application (or its parent process like Terminal/IDE) in macOS System Settings > Privacy & Security.")
if __name__ == "__main__":
get_itunes_library_info()
Debug
Known issues
breakingPyObjC has periodically dropped support for older Python versions to align with Python's end-of-life schedule and leverage newer Python features.fixEnsure your Python environment meets the minimum requirement. PyObjC 12.x requires Python 3.10+, PyObjC 11.x requires Python 3.9+.
affects: 11.0, 12.0
gotchaAccessing the iTunes/Music Library.framework requires 'Full Disk Access' permission for the Python application (or its parent process like Terminal/IDE) in macOS System Settings.fixGrant 'Full Disk Access' to your terminal, IDE, or the Python executable running the script in System Settings > Privacy & Security > Full Disk Access.
affects: All versions on macOS
gotchaPyObjC 10.3 introduced breaking changes regarding the interaction between `__init__` and PyObjC's `__new__` for Objective-C wrapped classes. While partially reverted in 10.3.1 for user-defined `__new__`, direct `__init__` usage with PyObjC-provided `__new__` might still behave differently.fixWhen subclassing Objective-C classes, generally avoid overriding `__init__` if `__new__` is not also overridden. If you must use `__init__`, ensure it's compatible with the new object creation flow or explicitly override `__new__` as well.
affects: 10.3, 10.3.1+
gotchaPyObjC 11.1 changed how it models 'init' family methods (e.g., `initWithObjects_`) to align with Clang's Automatic Reference Counting (ARC) behavior, specifically regarding reference stealing for `self` and returning a new reference. This could affect memory management or object lifecycle in advanced scenarios.fixReview custom Python wrappers around Objective-C `init` methods, especially those dealing with explicit retain/release cycles (though less common with modern ARC). Ensure your code correctly handles object ownership if directly interacting with such methods.
affects: 11.1+
Upgrade
Version history
12.2latest on PyPI · released May 30, 2026
Audit
Dependencies
pyobjc-corerequiredThis package provides specific framework bindings and relies on the core PyObjC bridge for Objective-C interaction.