How to update the cmus music library
Summary
Explaination of how to update the C* Music Player (cmus) library manually using commands like :add, :update-cache, and :clear, or automatically via a configuration file or a custom shell script with a key binding.
Introduction #
The C* Music Player, cmus, is a lightweight, terminal-based music player for Unix-like systems that supports various audio formats and powerful library management features. Users may have trouble updating the library due to incorrect music directory paths, outdated caches, missing permissions, or forgetting to run commands like :add or :update-cache.
For more useful commands, see the cmus cheat sheet.
This article explains how to update the cmus music library so that cmus reloads and updates the database with newly added music.
Manually refresh cmus library #
To update (reload/refresh) the cmus music library, use the following commands:
Add a music folder #
The following cmus command scans the specified directory and adds its music files to the library.
:add /path/to/your/music
Rescan the library #
The following cmus command rescans the existing music library for changes, updating file metadata and detecting new or modified tracks.
:update-cache
Remove missing files #
To remove missing files, run the following two cmus commands.
:clear
:add /path/to/your/music
Breakdown:
:clearremoves all tracks from the current library or playlist without deleting any files from the disk.:addscans the specified directory and adds its music files to the library.
Automatically update cmus library #
There are two ways to update the cmus library automatically. One is via a config file and the other is using a shell script. Neither option is particularly elegant, but it works.
Config file #
To regenerate the cmus library every time you start cmus - which is equivalent to an update/refresh/reload - you can simply add the following command sequence to the cmus config file (~/.config/cmus/rc).
clear
add ~/Music/
add /path/to/your/music
update-cache -f
Breakdown:
clear:
Removes all tracks from the currentcmuslibrary.add ~/Music/:
Scans the specified directory (~/Music/) and adds all supported audio files to thecmuslibrary. Adjust path or add paths needed, e.g./path/to/your/music.update-cache -f:
Forces a full rescan of the entire library, refreshing metadata and checking for changes in the files.
This sequence clears the library, adds files from the specified directory, and forces a metadata refresh.
Script #
If you do not want to regenerate the cmus library every time you start cmus, but still want to rebuild the database with a key, you can simply call a script with a key in cmus. Just do the following:
Create a Bash script
#!/bin/bash # Remove all tracks from cmus library without deleting any # files from the disk. cmus-remote -C clear # Scans the specified directories and adds contained music # files to the cmus library. cmus-remote -C "add ~/Music" cmus-remote -C "add /path/to/your/music" # Forces a full rescan of the entire library, refreshing # metadata and checking for changes in the files. cmus-remote -C "update-cache -f"In my case, I called the file
update-cmus-library.shand I’ve placed it in my~/Bindirectory.Make the script executable
chmod +x ~/Bin/update-cmus-library.shLearn more about permissions in Linux.
Bind the update script to
ukey incmus:bind -f common u shell ~/Bin/update-cmus-library.shIn
cmus, just useshift+Ctrl+vto pase this command. Press Enter and your are done. You can immediately use theukey to update the library.
In `cmus`, go to Settings View to check if the binding worked. It should be listed under Keybindings like that: common u shell ~/Bin/update-cmus-library.sh.
FAQ's #
Most common questions and brief, easy-to-understand answers on the topic:
How do I manually update my cmus music library?
You can manually update the library in cmus using :add /path/to/your/music to scan a directory or :update-cache to rescan the existing library.
What does the :clear command do in cmus?
The :clear command removes all tracks from the current cmus library without deleting any files from the disk.
How can I automatically update the cmus library?
You can add update commands to the cmus config file (~/.config/cmus/rc) or create a shell script that runs cmus-remote commands.
How do I bind a key to refresh the cmus library?
You can bind a key (e.g., u) in cmus using :bind -f common u shell ~/Bin/update-cmus-library.sh to run a custom update script.
Does cmus automatically detect new files in the music library?
No, cmus does not automatically detect new files. You must use :update-cache or set up an automatic update method.
Further readings #
Sources and recommended, further resources on the topic:
Author
Jonas Jared Jacek (J15k)
Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/License
How to update the cmus music library by Jonas Jared Jacek is licensed under CC BY-SA 4.0.
This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:
<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/how-to-update-cmus-library">How to update the cmus music library</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>For more information see the Ditig legal page.
