aboutsummaryrefslogtreecommitdiffstats

wallhaven-dl

Small PyQt6 app to search wallhaven.cc and download wallpapers, with a thumbnail grid for previews.

Requirements

  • Python 3
  • PyQt6 (QtWidgets + QtNetwork)

Install

Symlink the script, menu entry and icon into your home directory, so later updates of the repo apply without reinstalling (~/bin must be on PATH):

ln -s "$PWD/wallhaven-dl" ~/bin/wallhaven-dl
ln -s "$PWD/wallhaven-dl.desktop" ~/.local/share/applications/wallhaven-dl.desktop
ln -s "$PWD/wallhaven-dl.svg" ~/.local/share/icons/hicolor/scalable/apps/wallhaven-dl.svg
update-desktop-database ~/.local/share/applications
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor

To uninstall, remove the three symlinks.

Usage

./wallhaven-dl
  • SFW / Sketchy / NSFW tabs at the top switch which purity level is shown.
  • The size picker lists each connected monitor. Picking one shows wallpapers at least as large as that monitor, in its orientation (portrait for a vertical screen). "any size" drops the filter.
  • General / Anime / People checkboxes filter by category.
  • The row of color swatches under the search bar filters by dominant color ("any" turns it off). The API only accepts these 29 fixed palette colors. On a narrow window the row scrolls sideways.
  • Every filter change searches after a short pause, so a burst of clicks costs one API call. Tags, @username or id:<tag id> go in the search box (press Enter).
  • "Load more" fetches the next page of results.
  • Double-click a thumbnail (or press Enter) to open a preview panel on the right. It shows the full image, its details and colors, and a link to its wallhaven page. Its "Download" button saves the already loaded image without fetching it again.
  • Select one or more thumbnails (Ctrl/Shift-click) and press "Download selected" to download several at once.
  • Ctrl+Q quits.
  • Wallpapers already in your library are dimmed, with a large green check mark and "downloaded" over the thumbnail, and downloading skips them. The library is ~/Pictures/wallpapers/ and all its subfolders (hidden ones skipped), plus the save folder if it lives elsewhere. Files are recognized by the wallhaven id in their name, wallhaven-<id>.<ext> or renamed copies like wallhaven-<id>_2560x1080.png, so the same wallpaper is never downloaded into two folders. The library is rescanned on every new search.
  • The "Folder" button picks the save folder (default ~/Pictures/wallpapers/wallhaven/). The choice is remembered in ~/.config/wallhaven-dl/wallhaven-dl.conf.
  • "Find low-res on disk" lists images anywhere in the library that are smaller than the monitor they match (same orientation, largest such monitor). A wallhaven wallpaper exists at one resolution only, so double-clicking one searches for alternatives at that monitor's size instead. Files with a wallhaven id in their name are searched by their first tag, under their own purity. Any other file is searched by its dominant color, extracted locally (the image never leaves your machine): every pixel is mapped to the nearest of wallhaven's 29 palette colors, and the most common chromatic one is used, falling back to grey when no color covers at least 10% of the image. The status bar shows the top three colors, so you can click another swatch, and the purity tabs and category checkboxes refine the results as usual. The original image also opens in a small floating window titled with its name and resolution. It stays on top while you browse candidates, can be moved and resized, and is replaced by the next pick. While it is open, the preview panel has a "Replace original" button: after a confirmation it saves the previewed wallpaper into the original's folder, and only once that write succeeds moves the original to the desktop trash, so it can always be restored. wallhaven's own like:<id> similarity search would be better, but it sits behind a Cloudflare bot check that blocks API clients.

Filters are always sent explicitly, so the search preferences saved on your wallhaven account never apply. The API allows 45 requests per minute. The app caps itself at 40 and queues anything beyond that, showing the wait in the status bar. The meter at the right of the status bar shows how many API calls were made in the last 60 seconds. It is a sliding window, so each call drops off the meter one minute after it was made. Thumbnail and image downloads don't count toward the limit.

API key

NSFW results need a wallhaven API key (account settings on wallhaven.cc). The key is read at startup from pass, from the entry wallhaven.cc/api-key by default, or the one named in WALLHAVEN_PASS_ENTRY:

WALLHAVEN_PASS_ENTRY=wallhaven.cc/you ./wallhaven-dl

If the entry has an apikey: <key> line, that is used, so the key can live next to the site password. Otherwise the entry's first line is the key. Without a key the NSFW tab stays disabled. The key is sent only to the API, in the X-API-Key header.

License

GPLv2-only. See LICENSE.

Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.