albums

GitHub Actions Workflow Status GitHub Actions Workflow Status Python PyPI - Version PyPI - Status Buy Me a Coffee

Manage a library of music: validate and fix tags and metadata, rename files, adjust and embed album art, clean up and import albums, and sync parts of the library to digital audio players or portable storage.

Overview

albums works with media files and tags, but primarily acts on "albums" rather than individual files. Everything is done locally and an Internet connection is not required (although it can be configured to use an external tool to download cover art). It's a command-line app but it is designed to be user friendly, with interactive menus, rich text formatting, tables and even blocky graphics.

It can work with a single folder or scan a whole media library into its database to make subsequent operations fast. It has many automated checks and fixes for metadata-related issues such as track numbering (sequence, totals, disc numbers), album-artist fields, embedding cover art, etc. It supports marking albums as part of "collections," for example to make a list of albums to sync to a digital audio player. It can also perform the sync.

Why use albums instead of other music library tools?

Use them all; you don't have to decide. If you have missing metadata or unidentified recordings and you want to use online databases to fill in the blanks, Beets does that, and has some command line and library management features similar to albums. MusicBrainz Picard does too. For manually editing tags in a GUI with some fancy features and automation, puddletag and MP3TAG (proprietary but no cost for the Windows version) are nice, while EasyTAG is simple and quick.

albums is a little different. It works offline without external databases. It uses a series of independent, configurable checks and automated fixes for basic tags, cover art and filenames. You can review every change, or only the ones that require your choice. It also reports on some problems it can't fix, like missing tracks on an album. albums can help clean up and import new albums into your library and keep digital audio players synced. Its CLI plus JSON and SQL interfaces may enable some automation.

Supported Media

FLAC, Ogg Vorbis, MP3/ID3, M4A, ASF/WMA and AIFF containers/types are supported with standard tags. ASF/WMA embedded image support is read-only. Image files (PNG, JPEG, GIF, BMP, WEBP, TIFF, etc) in the album folder are scanned and can be automatically converted and embedded.

More formats and tag support will likely be added if requested.

System Requirements

Installation via pipx requires Python 3.12+ and should work on almost any 64-bit x86 or ARM system with Linux, macOS or Windows.

Binary releases for 64-bit Linux or Windows do not have any Python requirement. The Linux binary requires glibc 2.38, meaning recent distributions such as Ubuntu 24, Debian 13 (Trixie), Fedora 39 and Arch Linux. (Use the regular package to install on older distributions.)

albums is primarily tested on Linux and Windows.

Project links

Data verified by PyPI on Sep 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.32)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for 4levity from gravatar.com 4levity

Credits

Author: Ivan Cooper

GitHub Statistics

Data verified by PyPI on Sep 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python <3.15, >=3.12

Tags

flac id3 library mp3 music tags vorbis

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

albums-0.9.29.tar.gz (389.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

albums-0.9.29-py3-none-any.whl (224.3 kB view details)

Uploaded Python 3

File details

Details for the file albums-0.9.29.tar.gz.

File metadata

  • Download URL: albums-0.9.29.tar.gz
  • Upload date:
  • Size: 389.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for albums-0.9.29.tar.gz
Algorithm Hash digest
SHA256 583021e67a3155dd8b0cb74ebb317452d5047d70c636181be8e85777bf2741aa
MD5 45c4c86cca386ba303582ec182a1b155
BLAKE2b-256 ab241233ef59242bd31d9cc2dae6d45c64da2519326cd3ad3515d40f7e43309d

See more details on using hashes here.

Provenance

The following attestation bundles were made for albums-0.9.29.tar.gz:

Publisher: publish.yml on 4levity/albums

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file albums-0.9.29-py3-none-any.whl.

File metadata

  • Download URL: albums-0.9.29-py3-none-any.whl
  • Upload date:
  • Size: 224.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for albums-0.9.29-py3-none-any.whl
Algorithm Hash digest
SHA256 3fd6d78ac1b747ca2521b77eabd1396c2abe001b391fd71d4587df799f1ccb23
MD5 a07dd9d8cf6398e46e7f1868cd0b52b6
BLAKE2b-256 b3bee198f1071235b06c1dfe1802ce52a9f3f523513f9657f4e172c90b9e5209

See more details on using hashes here.

Provenance

The following attestation bundles were made for albums-0.9.29-py3-none-any.whl:

Publisher: publish.yml on 4levity/albums

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.9.32

2 files

0.9.31

2 files

0.9.30

2 files

This release

0.9.29 This release

2 files

0.9.28

2 files

0.9.27

2 files

0.9.26

2 files

0.9.25

2 files

0.9.24

2 files

0.9.23

2 files

0.9.22

2 files

0.9.21

2 files

0.9.20

2 files

0.9.19

2 files

0.9.18

2 files

0.9.17

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.13

2 files

0.9.12

2 files

0.9.11

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page