My first attempt at getting these two great tools working was a bit of a pain in the ass but it was totally worth it because it is by far the best way of organising and playing your music that I’ve ever used. Now that I’ve set it up a few times on various Linux builds I know it’s fairly straight forward but there are a few gotchas to watch out for so I’ve written this guide for future reference.

Installing NCMPCPP

Although it’s possible to install NCMPCPP with a simple apt install ncmpcpp I found that approach gave me a bunch of problems when configuring the software because the version you get using apt install is pretty old meaning many of the configuration guides I found online didn’t work (speaking of guides, the best one to follow and consult for trouble shooting is the ncmcpcc guide on

Instead I found it’s best to build it yourself from source as you’ll get the latest version and should find it easier to set up. First clone the source code then cd into the directory.

cd /usr/local/lib
sudo git clone
cd ncmpcpp

Now follow the steps in the INSTALL file to get it running. You’ll probably have to run the configure file a few times because it’ll complain about various packages not being found. I had to install the following packages:

sudo apt install libboost-all-dev
sudo apt install libmpdclient-dev
sudo apt install libcurl4-openssl-dev
sudo apt install libtag1-dev

That last item is called Taglib, it’s an optional package so the configure script won’t prompt you to install it, but without it the metadata editor feature of NCMPCPP won’t work. You’re probably gonna want to use the metadata editor so get Taglib installed before you run make to compile the NCMPCPP package.

Once you’ve successfully compiled the package you can make install then run ncmpcpp to start it up. It’ll probably say “connection refused” at the bottom because we’re yet to install and configure MPD.

Configuring NCMPCPP

You’ll need a folder for your config at ~/.ncmpcpp. The config file is just named ‘config’ and the bindings file is named ‘bindings’. Here is an example with some basic settings:

# ~/.ncmpcpp/config
ncmpcpp_directory = "/home/planteroast/.ncmpcpp"
mpd_music_dir = "/home/planteroast/gs-music"
mpd_host = "localhost"
mpd_port = "7700"
mpd_connection_timeout = "5"
mpd_crossfade_time = "0"

Note that I’ve set the port to 7700 instead of the default 6600, this is because I was getting some strange issues with Mint telling me that the port is already in use and I found setting the port it to something other than 6600 fixed it. If you do this then you’ll need to set the MPD port too (info on how to do it is later in this guide).

You can get a fresh version of the config file and the bindings file from the following locations and edit it with your settings.

# Fresh versions of the config and bindings to use as templates
cp /usr/share/doc/ncmpcpp/bindings ~/Desktop
cp /usr/share/doc/ncmpcpp/config ~/Desktop

Config variables not working?

Are you using the latest version? Many of the guides I’ve seen on the web use old verions and state outdated variables. It’s best to build the latest version yourself and use the latest config variables. Also, I’ve found while styling NCMPCPP that some of the variables don’t seem to work or maybe they do work but not in the way that the name suggests?

Metadata editor not showing?

You might find after installing MPD and NCMPCPP and successfully playing some music that the tag editor screen is not available when you push 6. This might be because when you built NCMPCPP you didn’t have taglib installed, as when its not available NCMPCPP will build itself without the tag editor feature. It’s listed as an optional dependency in NCMCPCC’s README file so if you install it then rebuild NCMPCPP it should work

Installing MPD

The details below are a summary of the full guide on so go check that out if it’s your first time installing and setting up MPD.

MPD can be easily installed with apt install, as can its command line user interface mpc. MPC is not necessary to play your music via NCMPCPP but you’ll need it when you install MPD in order to create a database. I think it might be possible to create the MPD database using NCMPCPP’s update command too? Either way, MPC comes in very handy later if you want to set up any custom key bindings or scripts for controlling your music so you might as well just install it.

sudo apt install mpd
sudo apt install mpc
mpc update

Running MPD

There are 2 modes which MPD can run in; system-wide, and per-user. For a basic music player setup per-user mode is what you need, or if you’re building a fancy multi user audio server you might want to look into system-wide mode.

# Run MPD in per-user mode (probably the one you want to use)

# Run MPD in system-wide mode (for advanced use such as always-on audio servers)
sudo systemctl start mdp

When running in system-wide mode you can stop MDP with sudo systemctl stop mpd and see the status of it with sudo systemctl status mpd.

Error about ‘plugin wildmidi is unavailable’

You might see an error when you run MPD relating to wildmidi being uninstalled or unavaliable. It seems to pop up all the time but it’s a low level warning which you can probably ignore unless you are using midi.

# Ignore this low level warning (unless you intend using midi)
decoder: Decoder plugin 'wildmidi' is unavailable: configuration file does not exist: /etc/timidity/timidity.cfg

Configuring MPD

The MPD configuration file belongs in ~/.config/mpd/mpd.conf. If you need a template configuration file there’s one in /user/share/doc/mpd which you can copy.

# Template for making a MPD config
mkdir ~/.config/mpd
cp /usr/share/doc/mpd/mpdconf.example ~/.config/mpd/mpd.conf

My personal config file look like this:

# ~/.config/mpd/mpd.conf
music_directory "/home/planetroast/gs-music"
bind_to_address ""
port "7700"
playlist_directory "/home/planetroast/gs-music/playlists"
metadata_to_use "artist,album,title,track,name,genre,date,comment"

Here’s an explanation of why I set the above settings:

Setting Why I changed it
music_directory Because I keep my music library somewhere else instead of the default ~/Music directory for organisational reasons
port Because I was getting errors about the default port of 6600 being in use and setting to something different fixed the problem
bind_to_address Because it was required to fix the ‘port in use’ issue
playlist_directory Because I keep my playlists somewhere else instead of the the default ~/.mpd/playlists
metadata_to_use Because it allows the metadata editor to update comments on songs (more info on this below)

Error about the MPD port already being in use?

This is probably because MPD is already running and you weren’t aware of it, it happens if you run mpd more than once. If you need to stop or restart MPD you should use the systemctl commands: sudo systemctl stop mpd.

In theory stopping MPD should be all you need to do but I’ve found on some Mint installations that the only way to solve the ‘port already in use’ issue is to change the port that MPD and NCMPCPP use. My configuration in this guide uses port 7700 instead of the default 6600 which fixed the problem for me.

Comment tags not saving in NCMPCPP?

Open the metadata editor screen in NCMPCPP (keybinding for this is number 6) and you’ll see the option to edit the comments for your songs, but you might find that any changes to the comment does not persist after saving. I spent fucking ages trying to solve this because I assumed it was an issue with NCMPCPP or with Taglib, but it turns out that it’s a MPD configuration issue.

The fix is easy, just add the comment attribute to the metadata_to_use setting of your mpd.conf. By default the string doesn’t contain comment so just add it in there and your comments should start saving.

# mpd.conf
metadata_to_use "artist,album,title,track,name,genre,date,comment"

Had I been looking for a solution in the MPD man page then I would have found it pretty quickly as it says it right there at the end of the description: The default is to use all known tag types except for comments.

# MPD Man page
metadata_to_use <tags>
	This specifies the tag types that will be scanned for and made available
	to clients. Note that you must recreate (not update) your database for 
	changes to this parameter to take effect. Possible values are artist, 
	album, title, track, name, genre, date, composer, performer, comment, 
	and disc. Multiple tags may be specified as a comma separated list. An 
	example value is "artist,album,title,track". The special value "none" 
	may be used alone to disable all metadata. The default is to use all 
	known tag types except for comments.