nekos-best.py

A simple async Python wrapper for nekos.best API.

Join the official Discord server here.

Requirements

aiohttp (>=3.6.2)

Installation

Make sure to have pip installed in your environement. It will also install all requirements.

pip install -U nekosbest

Example

import asyncio

from nekosbest import Client


async def main() -> None:
    client = Client()
    try:
        single = await client.get_image("neko")
        print(single)
        multiple = await client.get_image("neko", 3)
        print(multiple)
    finally:
        await client.close()


asyncio.run(main())

Recommended usage

Use Client as an async context manager so the underlying HTTP session is always closed cleanly, even if an error is raised:

import asyncio

from nekosbest import Client


async def main() -> None:
    async with Client() as client:
        result = await client.get_image("neko")
        print(result.url)
        if result.dimensions is not None:
            print(result.dimensions.width, result.dimensions.height)


asyncio.run(main())

Exception handling

All exceptions raised by the library inherit from NekosBestBaseError. The most common ones you may want to catch:

NotFound — the requested category did not exist on the API.
APIError — the API returned an unexpected non-2xx status. The status code is available on err.code.
ClientError — the HTTP client could not reach the API (DNS failure, timeout, connection reset, ...). The underlying aiohttp.ClientConnectionError is preserved on err.__cause__.

from nekosbest import APIError, Client, ClientError, NotFound


async def fetch(client: Client, category: str) -> None:
    try:
        result = await client.get_image(category)
    except NotFound:
        print(f"unknown category: {category}")
    except APIError as err:
        print(f"nekos.best returned {err.code}")
    except ClientError as err:
        print(f"could not reach nekos.best: {err.__cause__}")
    else:
        print(result.url)

Changelog

See CHANGELOG.md for the full release history, including migration notes for every breaking change.

Release files for nekosbest 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nekosbest 1.2.0
File	Size	Uploaded
nekosbest-1.2.0.tar.gz	19.6 kB	Apr 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nekosbest 1.2.0
File	Interpreter	ABI	Platform	Reset
nekosbest-1.2.0-py3-none-any.whl 20.8 kB Apr 23, 2026	Python 3	none	any	Details

Total release size: 40.4 kB

Release files / nekosbest-1.2.0.tar.gz

Download URL	nekosbest-1.2.0.tar.gz
Size	19.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`066f4cb7894d3cb987c6b3e5e84261ce6e4dcf94bb95027b15eade4706b4e3f2`
BLAKE2b-256 checksum How to use checksums	`8ec8274b21d767e8e8e27f6fb67626e7792ae08f13b9b783cfa5328b5a162119`
Upload date	Apr 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`

Release files / nekosbest-1.2.0-py3-none-any.whl

Download URL	nekosbest-1.2.0-py3-none-any.whl
Size	20.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`29e701a62464b39c91540ba1bd34f86216388846467e6d53893dfbc878b2d252`
BLAKE2b-256 checksum How to use checksums	`2bd88864c1b919e7b7549821d8eba3c54766e5606c042a975b1fd9b25e44b49e`
Upload date	Apr 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`