If you are trying to install beets on macOS using pipx and encounter a SystemError: buffer overflow coming from fcntl.ioctl, it is likely because pipx defaulted to Python 3.14.2.
Python 3.14 has introduced stricter buffer checks that break the way Beets detects terminal width on macOS.
File ".../beets/ui/__init__.py", line 715, in term_width
buf = fcntl.ioctl(0, termios.TIOCGWINSZ, " " * 4)
SystemError: buffer overflow
To fix this, you need to force pipx to use a stable Python version (like 3.13 or 3.12) and then manually inject the dependencies for your enabled plugins.
First, uninstall the broken version and reinstall it pointing to a stable Python interpreter (Homebrew paths used below as an example): Bash
Remove the broken installation
pipx uninstall beets
Reinstall using Python 3.13
pipx install beets --python /opt/homebrew/bin/python3.13
Because pipx uses an isolated environment, you must manually add the libraries required by your specific plugins. For common plugins like fetchart, embedart, web, and lastgenre, run: Bash
pipx inject beets requests flask pylast
Run the following to ensure everything is loaded correctly: Bash
beet --version
Note: I have reported this as an issue to the Beets GitHub repository regarding Python 3.14 compatibility.