Skip to main content

A Python wrapper around the Wallhaven API.

Project description


A Python wrapper around the Wallhaven API.


Using pip

pip install wallhaven

If you want to upgrade it, you can run

pip install --upgrade wallhaven

Building from source

  1. Install poetry.
  2. Clone the repository
git clone
  1. Go inside it.
cd wallhaven/
  1. Install wallhaven globally with poetry.
poetry install

Now, wallhaven is installed in editable mode on your system. This means that if you change something, it will be updated automatically.

If you wish to install wallhaven locally, use poetry to create a virtual environment. Run these commands before using poetry install:

poetry env use <path_to_python>
poetry shell
poetry install
  • Currently, wallhaven only works with Python 3.6 or greater.
  • You can learn more about Poetry here.


According to the official documentation, you can only make 45 requests per minute. An exception will be raised if you hit this limit. If your requests are being made too fast, you'll hit the limit before actually reaching 45.


from wallhaven import Wallhaven

# Instanciate it.
# For some operations, an API key must be provided.
wallhaven = Wallhaven(api_key)

# Get wallpaper metadata
data = wallhaven.get_wallpaper_info(wallpaper_id="r25peq") # Example id

# Get tag metadata
data = wallhaven.get_tag_info(tag_id=tag_id)

# Get user settings.
# An API key must be provided.
data = wallhaven.get_user_settings()

# Get the user's public collection
data = wallhaven.get_collection_from_username(username=username)

# Get the user's public and private collection.
# An API key must be provided.
data = wallhaven.get_collection_from_apikey()

# Get wallpapers from a user's collection.
# By default., this will return ALL wallpapers.
# You can specify a limit.
data = wallhaven.get_wallpapers_from_collection(username, collection_id, limit=25)

Example of data returned from wallhaven.get_wallpaper_info('r25peq')

  "id": "r25peq",
  "url": "",
  "short_url": "",
  "uploader": {
    "username": "NinjaFace",
    "group": "User",
    "avatar": {
      "200px": "",
      "128px": "",
      "32px": "",
      "20px": ""
  "views": 822,
  "favorites": 14,
  "source": "",
  "purity": "sfw",
  "category": "general",
  "dimension_x": 3840,
  "dimension_y": 2160,
  "resolution": "3840x2160",
  "ratio": "1.78",
  "file_size": 13313317,
  "file_type": "image/png",
  "created_at": "2020-01-02 21:08:37",
  "colors": ["#000000", "#424153", "#333399", "#663399", "#660000"],
  "path": "",
  "thumbs": {
    "large": "",
    "original": "",
    "small": ""
  "tags": [
      "id": 713,
      "name": "neon",
      "alias": "neon light, neon lights",
      "category_id": 4,
      "category": "Miscellaneous",
      "purity": "sfw",
      "created_at": "2014-03-05 02:13:24"
      "id": 1018,
      "name": "flowers",
      "alias": "flower",
      "category_id": 42,
      "category": "Plants",
      "purity": "sfw",
      "created_at": "2014-03-27 09:42:03"
      "id": 479,
      "name": "digital art",
      "alias": "Cgi, Digital 2D, digital artwork, digital compositions, graphic, graphics, Motion Design",
      "category_id": 25,
      "category": "Digital",
      "purity": "sfw",
      "created_at": "2014-02-17 08:14:11"


You can also search for wallpapers.

from wallhaven import Wallhaven, Parameters

# API key is only needed for NSFW images.
wallhaven = Wallhaven()

# Choose parameters for the wallpapers.
params = Parameters()
params.set_categories(general=True, anime=True, people=False)
params.set_range("Last Three Days") # or set_range("3d")

# Search for keywords

# Filter tags

# Filter by user
# Only returns wallpapers from this user.

# Search for wallpapers using chosen parameters.
data =

Each page contains 24 wallpapers. Search will return a list of dictionaries with the wallpapers' metadata. An empty list will be returned if no wallpapers were found.

Default parameters:

  • Categories: General, Anime, and People.
  • Purity: SFW
  • Sorting: Date Added
  • Range: Last Month (Ignored if 'Sorting' is not "Toplist")
  • Order: Descending
  • Page: 1

For more information about the API, visit the official documentation.


Performance is slowed down on purpose. This is to not overload the Wallhaven's server with requests. Currently, the program sleeps for 0.5 seconds after each request. Also, if you're requesting too fast you'll end up hitting the limit sooner.

You can change the request timeout by:

from wallhaven import Wallhaven

wallhaven = Wallhaven()

# Calling the variable directly.
wallhaven.REQUEST_TIMEOUT = <seconds>

# Using a method.


Class Wallhaven

  • def __init__(self, api_key=None)
  • def _request(self, url, **kwargs) -> requests.Response
  • def set_request_timeout(self, time: Union[int, float]) -> None
  • def get_wallpaper_info(self, wallpaper_id: Union[str, int]) -> Dict[str, Union[str, int, Dict[str, str], List[str], List[Dict[str, str]]]]
  • def get_tag_info(self, tag_id: Union[str, int]) -> Dict[str, str]
  • def get_user_settings(self) -> Dict[str, Union[str, List[str]]]
    • An API key must be provided.
  • def_get_collection_from_username(self, username: str) -> List[Dict[str, Union[str, int]]]
  • def get_collection_from_apikey(self) -> List[Dict[str, Union[str, int]]]
    • An API key must be provided.
  • def search(self, params: Dict[str, str]) -> List[Dict[str, Union[str, List[str], Dict[str, str]]]]
    • An API key must be provided (Only for NSFW wallpapers).

Class Parameters

  • def __init__(self)
  • def reset_parameters(self) -> None
    • Reset parameters to default.
  • def reset_filters(self) -> None
    • Reset all filters.
  • def get_params(self) -> Dict[str, str]
    • Return current parameters.
  • def get_filters(self) -> Dict[str, Union[str, Dict[str, List[str]]]]
    • Return current filters.
  • def set_categories(self, general: bool = True, anime: bool = True, people: bool = True) -> None
  • def set_purity(self, sfw: bool = True, sketchy: bool = False, nsfw: bool = False) -> None
  • def set_sorting(self, sorting: str = "Date Added") -> None
  • def set_range(self, top_range: str = "Last Month") -> None
  • def set_sorting_order(self, order: str = "Descending") -> None
  • def set_page(self, page_number: Union[str, int]) -> None
  • def set_search_query(self, query: str = "") -> None
  • def clear_search_query(self, include_filters: bool = False) -> None
    • Clear only the search query. May also clear filters.
  • def include_tags(self, tags: List[str]) -> None
  • def exclude_tags(self, tags: List[str]) -> None
  • def filter_by_user(self, username: str) -> None
    • Only return wallpapers uploaded by this user.


The following exceptions can be raised if something goes wrong:

  • ApiKeyError

    • Raised when trying to request NSFW wallpapers without an API key (or with a invalid one).
  • PageNotFoundError

    • Raised when the page is not found. Example: get_wallpaper_info is used with an ID that does not exist.
  • RequestLimitError

    • Raised when the request limit is hit. Limit is 45 requests per minute, or when requesting too fast.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for wallhaven, version 0.6.6
Filename, size File type Python version Upload date Hashes
Filename, size wallhaven-0.6.6-py3-none-any.whl (12.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size wallhaven-0.6.6.tar.gz (13.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page