Organize Your Media Library From the Command Line

beets-teaserUber geeks can do everything from the command line. They can send emails, browse the web, write documents and even listen to music. And now with Beets, they can even manage their media library without logging into a graphical environment.

In addition to managing music libraries, Beets can fix filenames and metadata of your music collection, fetch cover art and lyrics, transcode audio to different formats, and do a lot more.

Install Beets

Beets is available in the repositories of most popular distributions. However, the version in your distro's repository might not be the latest. The recommended way to install Beets is via PIP, which is a package management system used exclusively for installing packages written in Python.

The command:

sudo apt-get install python-pip

will install PIP and also its dependencies. Once installed, you can use PIP to install Beets with:

sudo pip install beets

Configure Beets

Unlike most command-line tools that ship with a working configuration file, you have to manually create the configuration file for Beets. The configuration is stored in a text file called "config.yaml" under the "~/.config/beets/" directory.

The configuration file will grow with time as you become more familiar with Beets. To begin with, start with the following entries:

directory: ~/Music/beets-music
library: ~/Music/beets-music/musiclibrary.blb

The directory option expects the full path to where you wish to store your music collection. Remember, this isn't the path to your existing music collection. Rather, this is the directory where Beets will store your music when you import files. The library path is where Beets will store the database file that stores the index metadata of your music files. Make sure you create the directories beforehand.

After creating the file, we need to import our music collection into Beets. By default, the app assumes that we'll organize all our music under the directory specified in the configuration file. You can either copy the music from where it resides currently, or you can move the music to save disk space.

If you wish to move the files into the specified directory, add these lines to the configuration file:

      move: yes

On the other hand, if you don't wish to change the location of your music files, you can specify the path to your music files in the directory option and use the following lines to inform Beets that you don't wish to copy or move files from the current location:

      copy: no
      move: no

Make note of the indents. The configuration file is in the YAML language which accepts spaces (and not tabs) to indent some lines. Refer to the official documentation for more configuration options.

Import music

With the configuration file in place, you're finally ready to import files. The command

beet import /path/to/music/files

will import your music. The command also copies or moves the files into your specified directory depending on the import options you specify in the configuration file. The import command will also attempt to fetch and add metadata to the files.


If it finds multiple choices for a track, Beets will let you select the one that matches the track. If none of the candidates match your album, press U, which tells Beets to import files as it is.

Note that the import process does not produce any output on the screen, except for when it lists the possible candidates based on metadata. The process can take a long time, so if you wish to import a large selection of files in one go, and don't want to be prompted again and again for the metadata information, use the -A option, such as

beet import -A /path/to/many/music/files/

This tells Beets that you don't want it to auto-tag the files.

beet ? import

will list all the import options that you can use.

Browse the library

After importing the files, you can use the following command to query the music library.

beet ls

This command expects a query string, and if you don't specify any delimiters, it will search all the metadata files for the supplied query string. So for example, if you use the "beet ls divine power" command, Beets will list all songs where both the words divine and power appear in the metadata, whether in the title, album, artist, and so on.

When you supply multiple keywords as the query string, the words are automatically joined with a Boolean AND operator. That is, Beets will only display results where both the words appear.

You can also restrict the searches to specific fields such as artist, album, year, such as "beet ls artist:Doc" or "beet ls year:2010".


You can also specify numeric range as a query, and combine it will other list options. For example, "beet ls -a year:2008..2012" will list all albums released between 2008 and 2012 and the command "beet ls format:MP3 bitrate:128000.." will list all MP3s where the bitrate is more than 128k.

As usual, the official documentation lists several more query options.

Extend Beets

You can extend the core functionality of Beets with plugins. Beets ships with several plugins by default, but they need to be enabled before you can use them.

Personally I prefer to fetch lyrics for songs during imports, retrieve cover art for albums, and provide new metadata sources, and more.

To enable the plugins you must add the following line to the "~/.config/beets/config.yaml" file:

plugins: lyrics fetchart scrub

The plugins: line expects a space separated list of all the plugins you wish to enable. In the above example, the Lyrics, FetchArt and the Scrub plugin are enabled.

You can also use the command

beet lyrics <song name></song>

to manually search for lyrics for a song. Beets will automatically store the lyrics in the database. You can then use

beet lyrics -p <song name></song>

command to print the lyrics on the screen. Beets will first search for the lyrics in the database and if it doesn't find a match, it'll fetch the lyrics from the online sources.


Beets also has a simple web UI. To use the web interface you need the Flask framework which you can install with the command

sudo pip install flask

Then put "web" in the plugins line in the configuration file and start the web server with "beet web." Now launch your web browser and head to "http://localhost:8337" to access the interface.

I've only captured a brief snippet of Beets potential in this tutorial but hopefully enough to leave a lasting taste.

Image credit: Daniel Paxton

Mayank Sharma

Mayank Sharma has been writing on Linux for over a decade and is a regular contributor to Linux Format magazine.

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox