Home/Support
Support
Getting installed, getting started, and getting unstuck. If none of this covers it, there's a real person at the other end of the contact links.
Installing EZLibrary
-
Download the installer
One
.pkgfile, about 9.1 MB. It installs the app, then kicks off a best-effort Homebrew bootstrap for the helper tools EZLibrary uses. -
Get past the Gatekeeper warning
EZLibrary isn't signed with an Apple Developer ID — that's a paid Apple programme, and this is a free project — so macOS will refuse to open the installer on the first attempt and say it's from an unidentified developer. This is expected, and here's how to get through it:
- Open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the EZLibrary message. Confirm with Touch ID or your password.
- On older versions of macOS you can instead Control-click the
.pkgin Finder, choose Open, then Open again in the dialog.
If that makes you uneasy, that's a reasonable instinct. The whole source is on GitHub under GPLv3, and you can build and run it yourself with
swift buildinstead. -
Run the installer
EZLibrary is installed to your Applications folder. The installer also starts a best-effort Homebrew setup for
yt-dlp,ffmpeg,ffprobeandfpcalc, and the app checks them again on launch. -
Open it
EZLibrary looks for your
_Serato_folder automatically, including on external drives. If it finds the wrong one, or you keep more than one, set the path in Settings.
Before your first big change, take a backup. Open the Backup tab and run a full backup once. EZLibrary snapshots every Serato file before it writes to it anyway, but a full backup is the thing you'll be glad of if something goes sideways.
The four most common jobs
Each of these is the short version. The feature pages go into more detail.
Get your missing tracks back
The single biggest win for most libraries, and the safest place to start.
- Plug in every drive your music lives on.
- Quit Serato.
- Open Missing Tracks and run the scan.
- Review the suggested new location for each track and confirm the ones that look right.
- Apply, reopen Serato, and check a few crates.
Clean up duplicates
Fingerprint-based, so it catches copies that don't share a filename.
- Run a full backup first — this one deletes files.
- Open Duplicates and scan the library.
- Work through the groups. Check the audio verification detail on anything surprising.
- Use Pick Best, or choose the keeper yourself.
- Delete the rest from the library, or from your disk as well.
Fill in missing tags
Fix a whole library's worth of blank genres and years in a few passes.
- Open Tracks & Tags and choose a scope — all tracks, or one crate.
- Click a completion stat (say Genre Filled) to filter to the tracks missing it.
- Select rows and either bulk-fill a value you know, or run an online lookup.
- Turn on Only Fill Empty so existing values aren't overwritten.
- Apply with Serato closed.
Rename files consistently
Without Serato losing the file — which is what normally happens.
- Set your filename template in Settings and watch the preview.
- In Tracks & Tags, select the tracks — start with one crate.
- Click Rename Files From Tags.
- Read the preview, including the list of what's being skipped and why.
- Apply with Serato closed, then reopen Serato and confirm the cues are still there.
Frequently asked questions
Cost and licensing
Is EZLibrary really free?
Yes. There's no paid tier, no trial, no account and no upsell. It's licensed under the GNU GPL v3, which means you're free to use it, read the source, share it and modify it. If you distribute a modified version, you have to release your changes under the same licence.
What's the catch?
There isn't one, but there is a trade-off you should know about: the installer isn't signed with an Apple Developer ID, so macOS will warn you the first time you open it. See Installing EZLibrary.
Can I use it for commercial DJ work?
Yes. The GPL doesn't restrict what you do with the software, only what you have to do if you redistribute a modified copy of it.
Is this made by Serato?
No. EZLibrary is an independent, community-built utility. It isn't affiliated with, endorsed by, or sponsored by Serato Audio Research. It reads and writes Serato's library file format so the two can work together, and nothing more.
Requirements and setup
What do I need to run it?
macOS 13 or newer, on either Apple Silicon or Intel — the app ships as a universal binary, so one download covers both.
Do I have to install ffmpeg or anything else?
Usually no. The installer starts a best-effort Homebrew bootstrap for
ffmpeg, ffprobe, fpcalc and
yt-dlp, and EZLibrary checks again on every launch. If Homebrew is
missing or the bootstrap fails, use the banner inside the app to install or update
them.
How does it find my Serato library?
It looks for your _Serato_ folder in the usual places, including external
drives. To point it somewhere specific, set the path in Settings, or launch it with the
EZLIBRARY_LIBRARY_DIR environment variable set to the folder that contains
database V2.
My music is on an external drive.
That's fine — mount the drive before you launch EZLibrary. If it isn't mounted, every track on it looks missing, and a repair run in that state would be repairing the wrong thing.
Does it work with Serato DJ Lite?
EZLibrary reads the on-disk library format that Serato DJ writes, so in principle yes. In practice, development and testing is done against Serato DJ Pro — that's what it's verified on. If you run Lite, take a backup first and tell us how it goes.
What about Rekordbox, Traktor or Engine DJ?
Not supported today. Transferring tracks, cues and crates between Serato and Rekordbox is on the roadmap — it's the highest-risk item on there, so it's deliberately scheduled last. Upvote it if you want it sooner.
How do I update, and how do I uninstall?
EZLibrary checks for updates when it launches and can install a new version for you in one click. You can also just download the latest installer and run it over the top.
To uninstall, drag EZLibrary.app from Applications to the Trash. Your
Serato library is untouched by this, and your backups stay where they are in
SeratoBackups.
Safety and your data
Will I lose my cue points, beat grids or play counts?
No — keeping them is the whole point of the app. Serato attaches cues and beat grids to a library entry, and it's replacing that entry that loses them. EZLibrary repairs entries in place instead: when a file is renamed, moved or relinked, the existing library row is re-pointed rather than deleted and recreated.
Cue points and beat grids embedded in the audio files themselves are also preserved through tag edits, including on files that use less common ID3 encodings.
Do I have to close Serato?
For anything that writes, yes — and EZLibrary will refuse rather than let you do it by accident. Serato holds its library in memory and writes the whole thing back out when it quits, so any change made underneath it would simply be overwritten. Browsing and scanning are fine with Serato open.
What happens to my crates when a file gets renamed or moved?
They're updated in the same operation. That means Serato's SQLite library,
database V2, your plain crates and your smart crates — a smart
crate keeps a materialised list of member paths alongside its rules, and one stale path
in there is enough to make Serato re-import the old name as a second, missing track.
Does anything about my library get uploaded?
No. Your library, your files and your paths never leave your Mac. The only network requests EZLibrary makes are ones you trigger yourself — an online metadata lookup, a playlist you pasted in, a purchase link, or the update check. There's no telemetry and no account.
Where do backups go, and how do I restore one?
Into a SeratoBackups folder, each in its own timestamped directory. They
are ordinary files, not a proprietary archive, so you can browse them in Finder.
To restore, quit Serato and copy the files back over your _Serato_ folder.
Automatic pre-write snapshots are kept separately from the backups you run yourself,
so a bad operation can be reversed even if you forgot to take a manual backup.
Is there an undo button?
Not as a single click, no — and it's better to know that up front. What there is instead: a timestamped snapshot of every Serato file taken before it's written, atomic writes so an operation can't leave a file half-finished, and read-back verification that rolls a change back if what landed on disk doesn't match what was intended.
Restoring is a matter of copying a snapshot back. Take a full backup before your first duplicate cleanup or consolidation and you'll always have a clean point to return to.
Troubleshooting
Tracks still show as missing in Serato after I repaired them.
- Make sure Serato was fully quit when the repair ran, not just minimised.
- Check the drive holding those files is mounted.
- Reopen Serato and give it a moment — it re-reads its library on launch.
If a repair left tracks in a worse state, that's a data-integrity bug and it goes to the front of the queue. Open an issue with what you ran and what you saw.
A huge number of my tracks are missing at once.
That's usually one move or one consolidation that went through without the library following it. The Missing Tracks tab handles it, but for thousands of entries the command-line repair is faster and shows you everything before it writes:
swift run EZLibraryCLI repair-locations --search /Volumes/Music
That previews only. Re-run it with --apply, with Serato closed, once the
preview looks right.
Duplicate detection says fingerprinting is unavailable.
Fingerprinting depends on fpcalc. The installer and the app both try to
provision it for you via Homebrew, so if it is missing the usual fix is to click the
install/update banner in EZLibrary and let it finish. The optional AcoustID lookup
still needs a free API key of your own — add it in Settings, or set
EZLIBRARY_ACOUSTID_KEY.
Discogs lookups aren't returning anything.
Discogs requires a personal access token. Generate one from your Discogs account and
add it in Settings, or set EZLIBRARY_DISCOGS_TOKEN. The iTunes and
MusicBrainz lookups work without any key.
The Finder right-click action isn't there.
It's installed separately, once:
/Applications/EZLibrary.app/Contents/Resources/scripts/install-finder-quick-action.sh
If it still doesn't appear, relaunch Finder and check that
~/Library/Services/Add To Serato Library.workflow exists.
A write operation failed. What now?
Nothing is half-applied — failed writes roll back. To work out why:
- Read the error message; they're written to be actionable rather than to look technical.
- Check the destination and library paths are writable and the drives are mounted.
- Retry on a smaller selection to isolate one problematic file.
The app crashes shortly after launch.
Try launching against an empty library to separate a data problem from a UI one:
EZLIBRARY_LIBRARY_DIR=/tmp/empty open -a EZLibrary
Then open an issue
with your macOS version and the most recent report from
~/Library/Logs/DiagnosticReports/.
There's a longer, more technical version of this in the troubleshooting guide, covering building from source and packaging.
Get in touch
Everything happens in the open on GitHub, so you can see what's been reported, what's been answered, and whether anything is actually getting fixed.
Something's broken
Bug reports are the most useful thing you can send. Include what you ran, what you expected, what happened, your macOS version, and whether your library is on an external drive.
You've got an idea
Feature requests go on the public roadmap, where anyone can upvote them. What gets built next is genuinely driven by what people vote for.
You just want to ask something
Questions, setup problems, "is this thing supposed to do that" — Discussions is the place, and the answers stay searchable for whoever hits the same thing next.
A security or data-loss issue
If you've found something that could corrupt or lose a library, or a security problem, please report it privately first rather than in a public issue.
This is a one-person project. Replies are usually quick but they aren't a support desk, and there's no SLA behind them. Data-integrity and security reports jump the queue over everything else.
Haven't tried it yet?
Free, open source, and it takes a backup before it touches anything.