# wallhaven-dl Small PyQt6 app to search [wallhaven.cc](https://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:` 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-.` or renamed copies like `wallhaven-_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:` 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](https://www.passwordstore.org/), 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: ` 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](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.