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 11, 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 11, 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.31.tar.gz (390.7 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.31-py3-none-any.whl (227.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: albums-0.9.31.tar.gz
  • Upload date:
  • Size: 390.7 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.31.tar.gz
Algorithm Hash digest
SHA256 fdef37884ddde9c07b4f8f186ed6bd992a6b60cb4d32eedba3641c68adc42c6c
MD5 6934e044d21f4ad9a7d35c497816cf77
BLAKE2b-256 fcf04b1f9e120b1306ec21c5d3975abad7857e78ac48e9dd911c7efda491a03f

See more details on using hashes here.

Provenance

The following attestation bundles were made for albums-0.9.31.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.31-py3-none-any.whl.

File metadata

  • Download URL: albums-0.9.31-py3-none-any.whl
  • Upload date:
  • Size: 227.9 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.31-py3-none-any.whl
Algorithm Hash digest
SHA256 3ed34af60a147674725099b179dbeaf7f0b283512ba72cdffe89f2e4cd7f7d45
MD5 31f9e3f203d905536e346fcbd95f41e8
BLAKE2b-256 fa57e51cbecdb79c22aeaaa2ca392e5f26177ad718c9e417e4842137a6e5240e

See more details on using hashes here.

Provenance

The following attestation bundles were made for albums-0.9.31-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

This release

0.9.31 This release

2 files

0.9.30

2 files

0.9.29

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