Wallhaven API for Java
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Release Build Status codecov

wallhaven4j is a Java library that allows you to search for wallpapers on Wallhaven and access its resources - wallpapers, collections, tags, and users.


  • JRE 7 or higher at runtime
  • JDK 8 or higher to compile the library from source



Step 1. Add the JitPack repository to your root build.gradle at the end of repositories:

allprojects {
    repositories {
      maven { url "https://jitpack.io" }

Step 2. Add the dependency:

dependencies {
    compile 'com.ivkos:wallhaven4j:1.3.0'


Step 1. Add the JitPack repository to your pom.xml file:


Step 2. Add the dependency:



Javadocs can be found here.

Quick Start

Important note: This library works by parsing the HTML of Wallhaven. Site design can change unexpectedly and potentially break the library, so until a fix is pushed you are advised to handle ParseExceptions gracefully at any Wallhaven operation. See Exception Handling below for more information.

Creating a Wallhaven session

// anonymous session
Wallhaven wh = new Wallhaven();

// log in with your wallhaven account
Wallhaven wh = new Wallhaven("USERNAME", "PASSWORD");

// log in with account and save session cookies to reuse later
Wallhaven wh = new Wallhaven("USERNAME", "PASSWORD", new File("/path/to/cookies.json"));


To search for wallpapers you need to first build a SearchQuery like so, and then use the search(...) methods of the Wallhaven object:

SearchQuery query = new SearchQueryBuilder()
            .keywords("cars", "bmw")
            .resolutions(new Resolution(1920, 1080), new Resolution(1280, 720))
            .ratios(new Ratio(16, 9))
List<Wallpaper> carWallpapers = wh.search(query);

If a filter is omitted, its default value will be used. Default values are defined in SearchQueryDefaults.

SearchQuery query = new SearchQueryBuilder()
            .ratios(new Ratio(9, 16))
List<Wallpaper> minimalWallpapers = wh.search(query);

If your application needs to fetch individual pages on demand, for example when doing lazy loading, you can do this like so:

SearchQuery query = new SearchQueryBuilder()

// fetch individual pages
List<Wallpaper> page1 = wh.search(query, 1);
List<Wallpaper> page3 = wh.search(query, 3);

Getting Resources by ID

Getting resources by their IDs is easy with the methods of the Wallhaven object:

Tag nature = wh.getTag(37);
User gandalf = wh.getUser("Gandalf");
Wallpaper doggo = wh.getWallpaper(254637);
WallpaperCollection wc = wh.getWallpaperCollection("Gandalf", 2);

Exception Handling

wallhaven4j parses Wallhaven's HTML. As a consequence, parsing may break if Wallhaven changes its design. It is recommended to be prepared to handle gracefully such cases. wallhaven4j has the following exception hierarchy:

  • WallhavenException
    • ConnectionException - problem with the HTTP connection to Wallhaven
    • LoginException - logging in to Wallhaven was unsuccessful due to incorrect credentials
    • ParseException - problem parsing Wallhaven's HTML
    • ResourceNotAccessibleException - the requested resource cannot be accessed due to privacy or purity restrictions
    • ResourceNotFoundException - the requested resource cannot be found