Listen to Music in the Terminal with MPD + ncmpcpp

MPD (Music Player Daemon) runs as a background service managing your audio library and playback engine. ncmpcpp is a feature-rich curses client that connects to MPD and gives you a full TUI interface — album art path rendering, tag editing, a spectrum visualiser, and snappy keyboard-driven browsing. Together they are a low-resource, scriptable music stack that survives reboots, SSH sessions, and desktop restarts without interruption.

Install MPD, MPC, and ncmpcpp

MPC is the minimal command-line client; it is also useful for scripting and quick verification.

Debian / Ubuntu

sudo apt update
sudo apt install mpd mpc ncmpcpp

Fedora / RHEL / Rocky (with EPEL enabled)

sudo dnf install mpd mpc ncmpcpp

Arch Linux

sudo pacman -S mpd mpc ncmpcpp

Configure MPD

MPD can run system-wide or per-user. Per-user is strongly recommended for a desktop: it runs under your UID, accesses your home directory without permission gymnastics, and integrates with your PulseAudio or PipeWire session.

Create the directory structure

mkdir -p ~/.config/mpd/playlists
mkdir -p ~/Music          # or wherever your library lives
touch ~/.config/mpd/database
touch ~/.config/mpd/log
touch ~/.config/mpd/pid
touch ~/.config/mpd/state

Write ~/.config/mpd/mpd.conf

cat > ~/.config/mpd/mpd.conf << 'EOF'
# Paths
music_directory     "~/Music"
playlist_directory  "~/.config/mpd/playlists"
db_file             "~/.config/mpd/database"
log_file            "~/.config/mpd/log"
pid_file            "~/.config/mpd/pid"
state_file          "~/.config/mpd/state"

# Networking — localhost only, default port 6600
bind_to_address     "127.0.0.1"
port                "6600"

# Audio output — PipeWire / PulseAudio (ALSA fallback shown commented)
audio_output {
    type    "pipewire"
    name    "PipeWire Sound Server"
}

# Uncomment for ALSA direct output instead:
# audio_output {
#     type    "alsa"
#     name    "ALSA Direct"
#     device  "hw:0,0"
# }

# Visualiser FIFO — required by ncmpcpp visualiser
audio_output {
    type            "fifo"
    name            "Visualiser FIFO"
    path            "/tmp/mpd.fifo"
    format          "44100:16:2"
}

# Normalise volume differences between tracks
replaygain          "album"
EOF

If you are on an older system still using PulseAudio rather than PipeWire, change the output type to "pulse". On a headless server, use "alsa" directly.

Enable and Start the Per-User systemd Service

Modern distros ship an MPD user-unit. Do not enable the system-wide mpd.service as well — that will cause port conflicts.

systemctl --user enable --now mpd.service

Verify it is running:

systemctl --user status mpd.service

Expected output will show Active: active (running). If the unit file is missing on your distro, start MPD manually with mpd ~/.config/mpd/mpd.conf and add that command to your shell profile.

Build the Music Library with MPC

MPC talks to the running daemon and triggers a database scan:

mpc update

Wait a few seconds (longer for large libraries), then check the count:

mpc stats

Output will look something like this (numbers will vary):

# Artists:   312
# Albums:    589
# Songs:   6 041
# DB Updated: Thu Jun 12 18:42:07 2025

Useful MPC one-liners for scripting and keybinds:

mpc play          # start playback
mpc toggle        # play/pause
mpc next          # skip forward
mpc prev          # skip back
mpc volume +5     # raise volume 5%
mpc random on     # enable shuffle

Configure ncmpcpp

Create the config file

mkdir -p ~/.config/ncmpcpp
cat > ~/.config/ncmpcpp/config << 'EOF'
# Connection
mpd_host                        = "127.0.0.1"
mpd_port                        = 6600
mpd_connection_timeout          = 5

# Library paths
mpd_music_dir                   = "~/Music"

# UI behaviour
song_list_format                = "$4%a$8 — $7%t$8 [$6%l$8]"
song_status_format              = "$6%a$8 — $7%t$8 ($b%b$8, %y)"
browser_sort_mode               = name
browser_sort_format             = "%a %t %e %n"
alternative_header_first_line_format = "$b$5%t$9$8"
alternative_header_second_line_format = "$3%a$9 — $6%b$9 (%y)"

# Colours (requires 256-colour terminal)
enabled_visualizer_sync_interval = yes
colors_enabled                  = yes
main_window_color               = white
color1                          = white
color2                          = cyan

# Visualiser
visualizer_fifo_path            = "/tmp/mpd.fifo"
visualizer_output_name          = "Visualiser FIFO"
visualizer_in_stereo            = yes
visualizer_type                 = spectrum
visualizer_look                 = ●▮
visualizer_color                = blue,cyan,green,yellow,magenta

# Keybinds comfort
cyclic_scrolling                = yes
seek_time                       = 5
volume_change_step              = 5
EOF

Launch ncmpcpp

ncmpcpp

Essential keyboard shortcuts

Key	Action
1	Current playlist
2	Browse filesystem / library
3	Search database
8	Visualiser screen
p	Play / pause
> / <	Next / previous track
+ / -	Volume up / down
r	Toggle repeat
z	Toggle shuffle
u	Update MPD database
q	Quit ncmpcpp (MPD keeps playing)

Enable the Visualiser

The visualiser requires a working FIFO output in mpd.conf (already added above) and a 256-colour terminal emulator (Kitty, Alacritty, foot, xterm-256color all work). Switch to the visualiser screen inside ncmpcpp with 8. If you see no animation:

• Confirm /tmp/mpd.fifo exists while MPD is running: ls -l /tmp/mpd.fifo
• Check that the visualizer_output_name string in your ncmpcpp config exactly matches the name field in the FIFO audio_output block of mpd.conf.
• Restart MPD after any mpd.conf change: systemctl --user restart mpd

You can cycle visualiser types (spectrum, wave, ellipse, oscilloscope) with w while on the visualiser screen.

Autostart MPD on Login

The systemctl --user enable command already handles this for graphical and console logins via systemd. If your session does not run a full systemd user manager (rare, but possible on minimal installs), add the following to ~/.bash_profile or ~/.zprofile:

# Start MPD if not already running
[ ! -s ~/.config/mpd/pid ] && mpd ~/.config/mpd/mpd.conf

Troubleshooting

MPD fails to start — "could not bind to port 6600"

Another instance is already running. Kill it with mpd --kill or check for a stale PID file: cat ~/.config/mpd/pid, then kill <pid>.

No audio output — PipeWire / PulseAudio

MPD must share the same PulseAudio/PipeWire session as your desktop. If you started MPD via a system service by mistake, disable it (sudo systemctl disable --now mpd) and use the user unit. Also confirm your user is in the audio group on older setups: groups $USER.

Library not showing files

MPD follows symlinks only if follow_outside_symlinks and follow_inside_symlinks are set to yes in mpd.conf. Also check that your files have standard audio extensions (.flac, .mp3, .ogg, .opus, .m4a) and readable permissions.

ncmpcpp shows "Connection refused"

Confirm MPD is actually running (systemctl --user status mpd) and that the host/port in ~/.config/ncmpcpp/config matches mpd.conf. Test with mpc ping — if MPC works, ncmpcpp config is the issue.