Cmus is a fantastic ncurses-based music player written in C. It can be used on all Unix-based operating systems, and so also on Linux. It has a series of very nice features like gapless playback, and supports a variety of file formats; among the others: Ogg Vorbis, MP3, FLAC, Opus, Musepack, WavPack, WAV, AAC, and MP4. It also support adding features via extensions. In this tutorial we will learn its basic usage.

In this tutorial you will learn:

  • How to install cmus on the most used Linux distributions
  • How to add songs to the library
  • How to reproduce a song, and the various reproduction modes
  • How to add and remove songs from the queue
  • How to create,rename,delete,import and export a playlist
  • How to add and remove songs from a playlist

Software requirements and conventions used

Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Distribution independent
Software cmus
Other None
Conventions # - requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ - requires given linux-commands to be executed as a regular non-privileged user


The cmus player is usually available in the official repositories of the most used Linux distributions. Fedora is an exception, but the player is available in the rpmfusion-free repository. Assuming we are using the last Fedora version (33), to the external repository to our software sources we should run the following command:

$ sudo dnf install

The command above will install and enable the rpmfusion-free repository for Fedora 33. Once the repository is enabled you should verify that the gpg signing key is correct. For rpmfusion 33 it is the following:

pub   rsa4096 2019-10-21 [SC]
uid           RPM Fusion nonfree repository for Fedora (2020) <>

At this point, to install cmus, we can run:

$ sudo dnf install cmus

On Debian-based distributions, we can choose to use apt-get:

$ sudo apt-get update && sudo apt-get install cmus

Cmus is present in the Archlinux community repository; we can install it via pacman:

$ sudo pacman -S cmus

First run

Now that cmus is installed, we can open a terminal emulator, and invoke it, just like any other command:

$ cmus

The player interface should appear:


What we see on screen is the so called album/artist view; as expected, no songs appears in the list since we didn’t import our music library yet.

Subscribe to RSS and NEWSLETTER and receive latest Linux news, jobs, career advice and tutorials.

Importing our library

What we should do now is to import our music library; to accomplish the task, all we have to do is to switch to the browser view. We can do that by pressing the 5 key:


As you can see in the screenshot above, the starting point of the navigation is the user HOME directory. We should now navigate to the directory containing our music library: we can use the arrow keys to move in the list, the backspace key to turn back to a previous directory, and the enter key to enter a directory. Once we reach the target directory in the browser view, to actually add the music it contains to the cmus library, all we have to do is to press the a key.

The operation could take a while to complete: this depends on the number of files existing in the directory. We can see the import is progressing since the minutes counter on the bottom right of the player interface is updating, displaying the total running time of the songs added to the library.

Once the import is finished, if switch back to the album/artist view (we can do that by pressing the 1 key), we can see our library is now populated:


On the left column we can see the list of all the artists. We can move in the list using the arrow keys. As we highlight an entry, on the right column all the albums belonging to the artists, and the related songs existing in the library will be displayed.

Reproducing an album/song

Reproducing a song is very easy: when in the album/artist view, if we want to reproduce all the albums of a specific artist, all we have to do is just to press the enter key once its name is highlighted in the left column. Alternatively, if we want to select a specific song, we should press the tab key to switch to the right column and then select the album and song we want to play, and, again, just press enter. The reproduction will begin:


As you can observe, the selected song will be “highlighted”. The title of the song will also appear on the the status bar at the bottom of the interface, together with the current and total running time. The volume percentage will also be displayed: to increase it or decrease it we can press the + and - keys respectively.

Once the song is playing, we can pause the reproduction simply by pressing the c key on our keyboard; to unpause, we just press the same key again. While the song is playing we can use the left and right arrow keys to backward or forward skip 10 seconds respectively, or the < or > keys to skip 1 minute in the same fashion.

To manually start playing the next song in the library we can press the b key, while to play the previous one, we can use z.

Modes of reproduction

In the bottom right corner of the player interface we can see the mode of reproduction, in this case “all from library”. The “main” modes of reproductions are:

  • all from library
  • artist from library
  • album from library

We can cycle through the reproduction modes by pressing the m key. The modes define the range of song which are considered in the library view. When using the all from library mode, all the song in the library will be considered. In the artist from library mode the player will consider only the songs in the library which belongs to the same artist of the song which is currently playing. Finally, in the album from library mode, the player will only consider the songs belonging to the same album of the one currently in reproduction.

Reproduction options

After the mode of reproduction, on the right side of the | symbol, we can see the C character. This is only one of the toggle which can be used to change the behavior of the player about songs reproduction. A character is displayed only if the corresponding function is activated. The most important functions are:

  • C (Continue)
  • R (Repeat)
  • S (Shuffle)
  • F (Follow)

If the C function is active, as in our case, when cmus finishes reproducing the currently playing song, it will automatically start playing the next one in the list. To toggle this functionality we must press shift+c.

If the R function is active cmus will start again reproducing the group of songs we selected once it reaches the end of the list. For example, if we are using the artist from library mode, once all the songs of the artist are played, the player will start reproducing the artist’s collection from the start. For this function to be effective the C function must also be active.

When the S function is active, the player is in shuffle mode, so it will choose random tracks from the library.

When the F function is active the player will always automatically select the current playing song on the list. To be more clear, suppose we have the C function enabled: when the player finishes playing the currently selected song it will start playing the next in the list, but, by default, it will not “select” it (it will not highlight it with the “selection bar”). When the F function is enabled, instead, the two things will always be in sync, and the song currently in reproduction will always be selected automatically.

Adding songs to the queue

While we are playing a song, cmus let us select other songs and add them to the list of the ones we want to reproduce. To add a song to the player queue, all we have to do is to select it and press the e key. To visualize the list of songs in the queue, we must switch to the queue view. To do that we must press the 4 key:


In this case you can see we added two song to the queue. To switch the order of the songs we can use the p or P keys. The first one moves the selected track downward, while the second moves it upward. To delete a song from the queue, we can press shift+d.


Cmus comes with a default playlist which is called “default”. Populating the playlist is a quite simple operation. Just like we did in the previous example, to add songs to the queue, we navigate our library and find the song we want to add to the playlist, then, instead of pressing the e key, we press y. We are not bounded to select one song at the time, we can select an entire album or the entire tracklist of an artist at once.

To visualize the list of songs we added to our playlist, we must switch to the playlist view. To do that we must press the 3 key. Here is an example of a playlist containing only three songs:


We can change the order of the songs in the playlist with the p and P keys, (just as we did before to order the songs in the queue) and we can press shift+d to delete a song from it.

Renaming a playlist

As we already said, “default” is the default playlist: this is highlighted by the fact that the name of the playlist is preceded by an asterisk *. We probably want to change its name. To do that we have to select it and press shift+; (so to obtain a colon). Doing so we will enter the “command” mode. At this point we must issue the pl-rename command followed by the new name we want to use for the playlist.

Adding a new playlist

In the most recent versions of cmus we can create multiple playlists. Adding a new playlist is quite simple. We enter the command mode by pressing shift+;, and this time we issue the pl-create command, followed by the name that should be used for the new playlist.

Once we add a new playlist, in order to populate it, we must mark it as the one that should be used when we decide to include a song. This is also a simple operation: all we have to do is to select it and press the space key. The fact that the playlist is now marked as the default one, is spotted by the asterisk which precedes its name.

Exporting and importing a playlist

Cmus comes with a very nice feature: the ability to export and import playlists. To export a playlist we select it in the playlist view, enter the command mode and issue the pl-export command followed by the path of the file that should be used to store it. For instance, to export the songs in a file called “exported-playlist”, we would run:

:pl-export exported-playlist

Once the playlist is exported, the file will contain the complete path of the songs included in it. For example:

/mnt/data/music/ripped/morituri/Pantera/Official Live - 101 Proof/02.Walk.flac
/mnt/data/music/ripped/morituri/Pantera/Official Live - 101 Proof/03.Becoming.flac
/mnt/data/music/ripped/morituri/Pantera/Official Live - 101 Proof/04.5 Minutes Alone.flac

Importing a playlist is just as simple: we enter the command mode and this time we issue the pl-import command, passing the path of the file containing the list of songs as argument. In our case we would run:

:pl-import exported-playlist

The name of the imported file will be used as the name of the new playlist which will contain all the included songs. If a file is named like an already existing playlist, the new one will be included with its name plus a suffix, for example default.1.

Deleting a playlist

Deleting a playlist is easy: all we have to do is to select its name in the playlist view and press shift+d. We will prompted to confirm we want to delete, and once we answer affirmatively, the playlist will be removed. Remember, however, that at least one playlist must always exist: if we attempt to remove the last playlist, we will receive an error:

Error: cannot delete the last playlist

Quitting cmus and saving settings

Once we finished listening to our favorite music, we want to exit cmus. Quitting the player is just a matter of pressing the q key: we will be asked to confirm we want to perform the action. If we want to exit the player right away, instead, we should enter the command mode (shift+;) and issue the q command. Our settings, playlist, etc are automatically saved on exit, but if we want to save them explicitly, while still in command mode, we can run the save command.

Closing thoughts

We reached the end of this tutorial: after reading it, you should be able to use cmus. We learned how to add songs to our library, how to reproduce them, how to add songs to a queue and how to manage playlists. We also learned how to toggle the various reproduction options. Here we only scratch the surface of all the functionality offered by cmus: to know more about this fantastic player, please consult its manual!

Submit your RESUME, create a JOB ALERT or subscribe to RSS feed.
Subscribe to NEWSLETTER and receive latest news, jobs, career advice and tutorials.
Get extra help by visiting our LINUX FORUM or simply use comments below.

Comments and Discussions