puddletag is a spreadsheet-style tag editor for Linux audio libraries

The spreadsheet layout is the design decision

The README states the difference from the alternatives plainly. puddletag is an audio tag editor, primarily created for GNU/Linux, similar to the Windows program Mp3tag, and the distinguishing feature is that unlike most taggers for GNU/Linux it uses a spreadsheet-like layout so that all the tags you want to edit by hand are visible and easily editable. That is the whole argument for the application, and it is a real one. A per-file dialog with a field for each tag forces you to work one file at a time and hides everything you did not think to open. A table shows every field of every selected file at once, so bulk edits are a selection and a keystroke. The intended user is someone with a library that accumulated inconsistent metadata over years, which is precisely the case where the usual tagger workflow becomes painful.

Functions and Actions cover the repetitive work

Beyond the table, the README names two extension points that do the bulk editing. Functions are the value transformations, and the examples given are replacing text, trimming it and doing case conversions. Actions automate repetitive tasks on top of that. Then there are web lookups, with Amazon for metadata including cover art, Discogs which also does cover art, FreeDB and MusicBrainz. The division between a Function and an Action is not spelled out further in the README, but the shape of the feature set is clear: Functions change a field's value, Actions do a multi-step operation over a set of files, and the metadata providers fill in what the filesystem does not know. That combination is what makes the application usable on a library where the tags are mostly missing rather than mostly wrong, since a lookup and a write-back is the operation you need most in that case.

The format list is wide, including the awkward containers

The supported format list is the technical core of the application, and it is broader than a typical tagger. ID3v1 and ID3v2 are covered, with ID3v2 in mp3 files and in AIFF, DSF and DSDIFF files. MP4 is covered for mp4 and m4a and similar. Vorbis Comments cover ogg, opus and flac. APEv2 covers Musepack mpc, Monkey's Audio ape and WavPack wv, and Windows Media covers wma. The listing of tag formats inside DSF and DSDIFF containers is the detail that shows how the author thinks about edge cases, since those are not audio formats anyone edits casually. The mechanism underneath is Mutagen, which the dependency list names as the tagging library, with the parsing work handled by pyparsing and the GUI by PyQt6.

Install from PyPI, or from a distribution package

The install section gives two routes, and the PyPI route is the one most people will use. The package is on PyPI, and the README notes that in addition to the full releases, every time a pull request is merged or a change is committed, a new version is automatically released on TestPyPI, so a pre-release can be tried if you want a new feature or a recent bug fix. Several tools can install it from PyPI, with pip, pipx, pipenv and others named, and the README strongly recommends an isolated, local environment, for example by installing with a local flag. That recommendation is the kind of thing that reads as boilerplate until you remember the dependency list includes a Qt binding and a fingerprinting library. The distribution packages are listed per platform, and Debian, Fedora, Solus and Nix are all covered with a single install command each.

Arch, Gentoo and Nix need a little more work

Not every distribution has a one-line install, and the README shows the differences. Arch is in the AUR rather than the official repositories, so the instructions are to clone the AUR repository, change into it and run makepkg with the install flag. Gentoo uses a layman overlay, with the overlay added by URL and the package emerged afterwards. Nix is available for the 24.05 and unstable channels, and the README gives both the NixOS and non-NixOS forms, distinguishing the classic nix-env call from the newer profile install with flakes, and it also shows the NixOS configuration snippet that adds the package to environment.systemPackages. That the README bothers with four different install shapes for one application is a fair sign of how distributed the Linux desktop is, and the package listings are maintained by named contributors, one per distribution in the Debian and Gentoo sections.

Running from source needs Python 3.13 and a virtual environment

The source route is for people who want the bleeding edge or who want to contribute, and the README is explicit that contributions are welcome. On Debian the dependencies are installed with apt, in a single command covering python3, mutagen, configobj, pyparsing, the PyQt6 packages including the Qt SVG module, unidecode and send2trash.

apt install python3 python3-mutagen python3-configobj python3-pyparsing python3-pyqt6 python3-pyqt6.qtsvg python3-unidecode python3-send2trash

Then the repository is cloned and the application is run from the checkout. The alternative is a virtual environment, and the README presents that as requiring only python and pip to be installed already:

git clone 'https://github.com/puddletag/puddletag.git'
cd 'puddletag'
python3 -m 'venv' '.'
bin/pip3 install -r 'requirements.txt'
bin/python3 'puddletag'

@@C1@@The virtual environment route creates the environment in the checkout directory itself, installs from a requirements file, and then runs the module from that environment. The requirements file is generated by pip-compile against Python 3.13, and the pins are what tells you how heavy the dependency tree is: PyQt6 at 6.11.0 with its Qt and SIP wheels, mutagen at 1.48.1, pyacoustid at 1.3.1 with requests and rapidfuzz behind it, lxml, configobj, pyparsing and unidecode. The setup metadata asks for Python 3.13 or newer and declares the project as a production stable end user desktop tool for Linux.

A GPLv3 project with translations and a plugin layer

The licence is stated at the end of the README: puddletag is licensed under the GPLv3, with the full text linked. The repository layout shows a project with an internationalisation story and an extension mechanism. There is a console/ directory, a puddlestuff/ package split into mainwin, libraries, audioinfo, tagsources with an mp3tag subpackage, masstag and plugins subpackages, and the setup.py package list mirrors that structure exactly, with the data directory and the compiled translations shipped as package data. A puddletag.1 man page, a puddletag.desktop entry, an XPM icon and a create_macos_app_bundle.sh script sit at the root, along with a release script, a get_tag.py and a restore_tag.py pair, a tagbackup.py, an update_translation.py helper and a THANKS file. The test configuration in pyproject.toml separates the slower interface-building tests behind a ui marker, so they can be skipped, and the coverage source is the puddlestuff package.

Editorial conclusion

puddletag suits a Linux user with a large, inconsistent music library who wants to see every tag of every file in one table and fix it in bulk, and who wants pattern-based renaming rather than a per-file dialog. It does not suit a Windows or macOS user, since it was created for GNU/Linux and the README asks for an issue if macOS support is wanted, and it does not suit someone who wants a modern-looking tagger with no Qt dependency. Before adopting, check that the format you care about is in the supported list, note that the source install needs Python 3.13 or newer, and remember that the last push to the repository was on 2026-10-19 with release 2.5.0 from 2025-07-27 under the GPLv3 or later.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. puddletag/puddletag on GitHub
4. README
5. Releases