Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Python bindings for Derpibooru's API

Project description


Python bindings for Derpibooru's API

License: Simplified BSD License

Version Version
Python Versions
Downloads Downloads

About this Fork

This is a fork of the joshua-stone/DerPyBooru repository; it is meant to be a drop in replacement for the modules in that package.


  • High-level abstraction over Derpibooru's REST API
  • Parameter chaining for ease of manipulation
  • Syntactic sugar for queries, e.g., "query.score >= 100" compiling to "score.gte:100"
  • Design focusing on iterables and lazy generation for network efficiency


  • python 2.7, 3.0 or newer
  • requests

How to install

  pip install derpybooru-nullforce

Checking documentation

  pydoc derpibooru

Typical usage

Getting images currently on Derpibooru's front page

from derpibooru import Search

for image in Search():
  id_number, score, tags =, image.score, ", ".join(image.tags)
  print("#{} - score: {:>3} - {}".format(id_number, score, tags))

Searching posts by tag

from derpibooru import Search

for image in Search().query("rarity", "twilight sparkle"):

Crawling Derpibooru from first to last post

from derpibooru import Search

# This is only an example and shouldn't be used in practice as it abuses
# Derpibooru's licensing terms
for image in Search().ascending().limit(None):
  id_number, score, tags =, image.score, ", ".join(image.tags)
  print("#{} - score: {:>3} - {}".format(id_number, score, tags))

Getting random posts

from derpibooru import Search, sort

for post in Search().sort_by(sort.RANDOM):

Getting top 100 posts

from derpibooru import Search, sort

top_scoring = [post for post in Search().sort_by(sort.SCORE).limit(100)]

Storing and passing new search parameters

from derpibooru import Search, sort

params = Search().sort_by(sort.SCORE).limit(100).parameters

top_scoring = Search(**params)
top_animated = top_scoring.query("animated")

Filtering by metadata

from derpibooru import Search, query

q = {
  query.width == 1920,
  query.height == 1080,
  query.score >= 100

wallpapers = [image for image in Search().query(*q)]

Getting the latest images from a watchlist

from derpibooru import Search, user

key = "your_api_key"

for post in Search().key(key).watched(user.ONLY):
  id_number, score, tags =, post.score, ", ".join(post.tags)
  print("#{} - score: {:>3} - {}".format(id_number, score, tags))





  • Image class now has an image_json property to get to the underlying JSON field (image still returns representations["full"] but will change to the JSON value in a future version).


  • Updated Search methods to use q= params:
    • faves uses my:faves
    • upvotes uses my:upvotes
    • uploads uses my:uploads
    • watched uses my:watched

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 DerPyBooru-Nullforce, version 0.10.0
Filename, size File type Python version Upload date Hashes
Filename, size DerPyBooru_Nullforce-0.10.0-py2.py3-none-any.whl (15.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size DerPyBooru_Nullforce-0.10.0.tar.gz (9.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page