cmus: a terminal music player built around a small C core and loadable output plugins

What cmus is and who it is for

cmus is described in its README as a "Small, fast and powerful console music player for Unix-like operating systems." The repository is written in C and licensed GPL-2.0. The last push to the default branch was on 2026-08-12, and the most recent tagged release listed is v2.12.0 from 2024-10-26.

The target user is someone who plays local audio files from a terminal and does not want a window, a tray icon or a media framework dependency graph. That is a narrower audience than a desktop player serves, and the README does not try to widen it. There is no mention of a mobile client, a web interface or a cloud library. What the README does mention is an IRC channel on Libera.chat and a GitHub issue tracker, which tells you where the project expects users to go.

The practical consequence is that cmus is a good fit when your music is already on disk and organized enough to browse by directory or by tags. It is a worse fit when your listening depends on a service rather than files.

How the C core, plugins and remote control fit together

The repository layout shows a single binary assembled from many object files. The Makefile lists the cmus target as ape.o, browser.o, buffer.o, cache.o, channelmap.o, cmdline.o, cmus.o, command_mode.o, comment.o, convert.lo, cue.o, cue_utils.o, debug.o, discid.o, editable.o, expr.o, filters.o, format_print.o, gbuf.o, glob.o, help.o, history.o, http.o, id3.o, input.o, job.o, keys.o, keyval.o, lib.o, load_dir.o, locking.o, mergesort.o, misc.o, options.o, output.o, pcm.o, player.o, play_queue.o, pl.o, pl_env.o, rbtree.o, read_wrapper.o, search_mode.o, search.o, server.o, spawn.o, tabexp_file.o, tabexp.o, track_info.o, track.o, tree.o, uchar.o, u_collate.o, ui_curses.o, window.o, worker.o and xstrjoin.o.

Two things stand out in that list. First, ui_curses.o and the ncurses dependency in the README confirm the interface is a curses terminal UI, not a wrapper around one. Second, the split between input.o, output.o, player.o, pcm.o and convert.lo points at a pipeline: decoders feed PCM, converters handle format and channel layout, and output plugins consume the result. The README's dependency tables support that reading, since it says all dependencies other than pkg-config, ncurses, iconv and elogind/systemd are for optional input/output plugins.

The Makefile also shows a separate cmus-remote binary built from main.o, file.o, misc.o, path.o, prog.o and xmalloc.o, and it compiles server.o and main.o with DEFAULT_PORT=3000. That is the mechanism behind remote control: a small client talks to the running player over a port, so you can drive playback from a script or another terminal. The README itself does not document the remote protocol, so the port number in the Makefile is the concrete detail available rather than a documented interface contract.

Versioning has its own quirk. The Makefile derives VERSION from git describe, falling back to a short SHA and finally to a hand-made v2.12.0 string. Builds from a tarball without git history will therefore report a different version string than builds from a clone.

Installing cmus and playing a first track

The README gives the build sequence directly. Dependencies come first, and the README lists per-distribution package sets. On Debian or Ubuntu the documented command is:

apt install pkg-config libncursesw5-dev libfaad-dev libao-dev libasound2-dev libcddb2-dev libcdio-cdda-dev libdiscid-dev libavformat-dev libavcodec-dev libswresample-dev libflac-dev libjack-dev libmad0-dev libmodplug-dev libmpcdec-dev libsystemd-dev libopusfile-dev libpulse-dev libsamplerate0-dev libsndio-dev libvorbis-dev libwavpack-dev

That is the full optional set. You can install fewer packages; the README states that features are auto-detected, so anything missing simply will not be compiled in. After dependencies, configure and build:

./configure
make

The README notes that on some BSD systems you need gmake instead of make, and that running ./configure --help lists all configuration options. The generated config.mk shows which features were enabled, through CONFIG_* entries. To see what your build picked up, read that file rather than guessing.

Installing system-wide, or into a staging directory for packaging:

make install
make install DESTDIR=~/tmp/cmus

Once installed, the documented starting point is the tutorial man page:

man cmus-tutorial

A second page, man cmus, covers the reference material. The README does not reproduce the key bindings or command syntax, so the man pages are the actual documentation rather than a supplement to it. If you want to try cmus without installing it, running the built binary from the source directory works, but the README does not describe that workflow explicitly.

Where cmus is the wrong tool

The clearest limitation is that the README does not document a stable release binary. Installation means configure, make and make install, or a package from your distribution. If you are on a platform where neither applies, the README offers no alternative path.

Optional dependencies are the second constraint. Because features are auto-detected at configure time, two machines running the same cmus version can decode different formats. A file that plays on your desktop may be silently unsupported on a server where libmad, libvorbis or libopusfile were never installed. The README's dependency tables make this visible, but nothing warns you at runtime beyond the fact that the track will not play.

Remote control is the third. The Makefile sets DEFAULT_PORT=3000 for the server and remote client, and the README does not document authentication or transport security for that port. If you expose it beyond localhost, that is your decision and your risk, not something the documentation addresses.

Finally, the README states that the IRC channel is unofficial and that the people there are present "for the love of cmus." That is an honest description of the support model. There is a GitHub issue tracker with a template for collecting information, and debug output can be written to ~/cmus-debug.txt when configured with DEBUG=2, but there is no commercial support path and no stated response time.

How cmus differs from MPD and from graphical players

The most useful comparison is with MPD, the Music Player Daemon. MPD splits the player into a long-running daemon and separate clients, so the daemon owns the library and playback state while any number of front ends connect to it. cmus keeps the player and the curses interface in one process, with cmus-remote as a thin client for control. If you want several different clients, including graphical ones, attached to a single library, MPD's architecture is the one designed for that. If you want one terminal program you start and stop as needed, cmus avoids the daemon management entirely.

Against graphical players, the difference is not just the interface. A typical graphical player pulls in a toolkit and a media framework, and its feature set is organized around album art, visual browsing and library scanning. cmus is organized around a curses UI, a directory browser, playlists, filters and a search mode, all visible as separate source files in the repository. There is no album art pipeline in the README or the file list.

That trade-off cuts both ways. cmus starts fast and stays out of the way, but anything you would click through in a graphical player has to be learned as a command or key binding from the man pages. The README points you at cmus-tutorial for exactly that reason.

Maintenance, upgrades and licence

The repository is not archived, and the last push was on 2026-08-12. Tagged releases are less frequent: v2.12.0 on 2024-10-26, v2.11.0 on 2024-05-11, and v2.10.0 on 2022-07-05. That pattern suggests development continues between releases while the release cadence is slow.

Upgrade cost is low in one respect and awkward in another. The build has no runtime package manager and no plugin registry to update, so upgrading means rebuilding from source or waiting for your distribution to package the new tag. Because the version string is derived from git describe when built from a clone, a source build and a distribution package can report different versions for what is effectively the same code, which complicates bug reports.

On licensing, cmus is GPL-2.0. If you redistribute a modified binary, the licence's source-availability terms apply, and the COPYING file in the repository root is the authoritative text. If you are embedding cmus or linking it into another product, that is a question for your own legal review rather than something this article can settle. Nothing in the README describes an exception, a linking clarification or a commercial licence option.

Editorial conclusion

cmus fits users who work in a terminal, keep local music files, and are willing to build from source or install a distribution package, since the README documents ./configure, make and make install rather than a binary release. It is a poor fit if you need a graphical library browser, streaming service integration, or a project with a formal support commitment. Before adopting it, check which optional codecs your distribution packages provide, because the README lists many dependencies as optional input/output plugins, and run ./configure --help to see what your system will actually build in.

Frequently asked questions

Official sources

1. cmus/cmus on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases