Artwork location resolution

Artists

Fetching images for artists is controlled by the ArtistArtPriority config option. This is a comma-separated list of places to look for artist images. The default is artist.*, album/artist.*, external, meaning:

• First try to find an artist.* image in the artist folder(s)
• If not found, try to find an artist.* image in one of the album folders for this artist
• If not found, try to fetch it from an external service
• If not found, use the artist image placeholder (grey star image)

You can also configure a centralized folder for artist images using the ArtistImageFolder config option and adding image-folder to ArtistArtPriority. When configured, Navidrome will look for image files in that folder named after the artist’s MusicBrainz ID or name.

Albums

CoverArt fetching for albums is controlled by the CoverArtPriority config option. This is a comma-separated list of places to look for album art images. The default is cover.*, folder.*, front.*, embedded, external, meaning:

• First try to find a cover.*, folder.* or front.* image in the album folder(s)
• If not found, try to read an embedded image from one of the mediafiles for that album
• If not found, try to fetch it from an external service (currently only Last.fm)
• If not found, use the cover placeholder (blue record image)

Disc Cover Art

Multi-disc albums can have disc-specific artwork. Navidrome uses the DiscArtPriority config option to find disc-level images. The default is disc*.*, cd*.*, cover.*, folder.*, front.*, discsubtitle, embedded, meaning:

• First try to find a disc*.* or cd*.* image in the disc’s folder
• Then try cover.*, folder.*, or front.* in the disc’s folder
• The special keyword discsubtitle matches image files whose filenames equal the disc’s subtitle
• Try to read an embedded image from one of the mediafiles for that disc
• If no disc-specific image is found, fall back to the album-level artwork

Example directory layout for a multi-disc album:

Music/
└── Artist - Album/
    ├── disc1/
    │   ├── disc1.jpg        ← matched by disc*.*
    │   ├── 01 - Track.flac
    │   └── 02 - Track.flac
    ├── disc2/
    │   ├── cd2.png          ← matched by cd*.*
    │   ├── 01 - Track.flac
    │   └── 02 - Track.flac
    └── cover.jpg            ← album-level fallback

Forcing the Album Artwork for All Discs

If you prefer every disc in a multi-disc album to display the album cover (instead of any disc-specific image or the embedded image of a track), set DiscArtPriority to an empty string:

DiscArtPriority = ""

With no disc-level sources to try, Navidrome skips straight to the album-level artwork fallback, so all discs share the same cover as the album. This is useful when your library has inconsistent or unwanted disc-specific images (e.g. embedded art that differs from the album cover) and you want a uniform look across discs.

MediaFiles

Some players (including Navidrome’s own WebUI) can display different cover art images for each track in an album. Navidrome resolves mediafile artwork in the following order:

1. Try to read an embedded image from the mediafile itself
2. For multi-disc albums, fall back to the disc-level artwork (see Disc Cover Art above)
3. Fall back to the album cover art

MediaFile cover art can be slow in some systems and can be disabled by setting EnableMediaFileCoverArt=false.

Playlists

Playlist artwork is resolved in the following order:

1. Uploaded image: A custom image uploaded via the web UI (see Artwork Uploads below)
2. Sidecar image: An image file with the same base name as the playlist file, placed alongside it
3. M3U directive: An image URL specified via the #EXTALBUMARTURL directive inside the M3U file. To allow HTTP/HTTPS URLs, set EnableM3UExternalAlbumArt to true in your configuration. Local file paths are always accepted.
4. Tiled image: An auto-generated mosaic of up to 4 album covers from the playlist
5. If none of the above are available, the album cover placeholder is used

Example of a playlist with a sidecar image:

Playlists/
├── My Playlist.m3u
└── My Playlist.jpg          ← sidecar image

Artwork Uploads

Navidrome allows uploading custom images for playlists, artists, and internet radio directly from the web UI. This is controlled by the EnableArtworkUpload config option (enabled by default). When disabled, only admin users can upload artwork.

Supported formats: JPEG, PNG, WebP, GIF Maximum file size: 10 MB Storage location: Uploaded images are stored in <DataFolder>/artwork/, organized by entity type (artist/, playlist/, radio/)

Playlist Cover Art

To upload a custom playlist cover, open the playlist in the Navidrome web UI and hover the mouse over the current artwork. You should see a camera icon where you can click to select the image to upload. Uploaded images take priority over all other playlist artwork sources.

Artist Images

Custom artist images can be uploaded via the web UI on the artist detail page. Follow the same process as the playlist cover art.

Internet Radio Images

You can also upload a custom image on the internet radio’s edit page. This image will be used as the station’s artwork instead of fetching its favicon (when available).

Image Format & Quality

By default, Navidrome encodes resized artwork as JPEG (or PNG, for PNG sources and square thumbnails). You can opt into WebP encoding for smaller images by enabling the EnableWebPEncoding config option (default: false), at the cost of more CPU when resizing. Note that some older clients may not be able to display WebP images.

The CoverArtQuality config option controls the encoding quality for resized JPEG and WebP output (default: 75). It does not apply to PNG.

Animated GIFs embedded in or associated with your music files are preserved during resize. They are converted to animated WebP using ffmpeg.

Troubleshooting

When artwork is wrong or missing, start with one affected album or artist, not the whole library. Recent versions of Navidrome include the navidrome artwork CLI commands, which show what happened. artwork explain prints the priority chain recorded for one item. It shows which candidate won, why the others lost, and whether a file was missing or present but unreadable. artwork status shows the queue, how many items have no image, and whether artwork settings changed since the last full reprocess.

Navidrome doesn’t retry missing artwork by itself. Changing an artwork setting doesn’t update artwork that is already stored, either. navidrome artwork reprocess handles both. Use --source absent to retry missing artwork, or --all to apply a setting change. For a single album or artist, admins can use Refresh Metadata in its context menu.

Finding out why one item has no artwork

1. Run the commands with your server’s settings. The CLI must read the same configuration file and data folder as the server, or it looks at a different database. Pass them with --configfile and --datafolder if they are not in the default location. In Docker, run the commands inside the Navidrome container, as explained in Running the CLI in Docker:

   navidrome --configfile /etc/navidrome/navidrome.toml artwork status
   docker compose exec navidrome navidrome artwork status
   

2. Check the overall state. navidrome artwork status shows how many items have no image, and how many gave up after repeated errors. It also tells you if you changed an artwork setting since the last full reprocess.

3. Explain one item. Open the album or artist in the web UI and copy its ID from the URL. It is the part after /album/ or /artist/. Then run:

   navidrome artwork explain <id>
   

   The Chain table lists every place Navidrome tried, and what happened at each. miss means nothing was there. unreadable means a file exists but Navidrome could not open or decode it, so check that file. skipped and error have the reason in the DETAIL column. The command reads the result Navidrome recorded, and it makes no external requests. Add --live only when you want it to try again now.

4. Fix the cause, then resolve that item again with navidrome artwork refresh <id>. If many items had the same problem, use navidrome artwork reprocess --source absent --dry-run to preview the bulk retry before you run it.

Asking for help

If you still need help, open a discussion and include:

• Your Navidrome version (shown in the web UI’s About dialog, or with navidrome --version) and how you installed it (Docker, binary, package manager, Windows installer, and so on).
• Where the missing image should come from: embedded in the music files, a local image file next to the music (such as cover.jpg or artist.jpg), or an external service such as Last.fm.
• The output of navidrome artwork status, and of navidrome artwork explain for the one item.

Before you post, remove passwords, API keys, tokens, and private URLs, such as your server’s address, from the output and your configuration.