-
Notifications
You must be signed in to change notification settings - Fork 0
Documentation
Downloads all images from a gallery into a local directory.
download(gallery_id: int, path: str = "downloaded", metadata: bool = False) -> bool
from nhentai_tools import extract_title, GalleryNotFoundError, RequestBlockedError
try:
title = extract_title(999999999)
except GalleryNotFoundError:
print("This gallery doesn't exist.")
except RequestBlockedError:
print("Blocked or rate limited, try again later.")
Both exceptions expose a .message attribute and format to that message when printed.
To reduce the chance of getting blocked by nhentai:
- All single-gallery
extract_*functions (tags, characters, languages, categories, artists, parodies, groups) wait a random 1–3 second interval before making their request. - Mass download functions (
tag_download,artist_download,character_download,parody_download) additionally wait 15–50 seconds between listing pages.
This is automatic and not currently configurable. Because of it, mass downloads over listings with many pages will take noticeably longer than a single download() call.
extract_title(gallery_id: int) -> str
Returns the gallery title with spaces replaced by hyphens. Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked or rate limited (HTTP 403/429).
extract_tags(gallery_id: int) -> list[str]
Returns a list of tags. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting (see Rate limit protection).
extract_artists(gallery_id: int) -> list[str]
Returns a list of artists. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_characters(gallery_id: int) -> list[str]
Returns a list of characters. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_parodies(gallery_id: int) -> list[str]
Returns a list of parodies. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_groups(gallery_id: int) -> list[str]
Returns a list of groups. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_languages(gallery_id: int) -> list[str]
Returns a list of languages. Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_categories(gallery_id: int) -> list[str]
Returns a list of categories (e.g. doujinshi, manga). Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_number_of_pages(gallery_id: int) -> int
Returns the total number of pages in the gallery. Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedErrorif the request was blocked.
extract_server(gallery_id: int) -> str
Returns the CDN server URL where the gallery's images are hosted (e.g. https://i3.nhentai.net/). Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked.
extract_gallery_server_id(gallery_id: int) -> int
Returns the internal server-side ID used to locate images on the CDN.
nhentai galleries have two IDs: the public one in the URL (
nhentai.net/g/<id>) and an internal server-side ID used for CDN image storage. This function returns the latter.
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked.
Downloads all images from a gallery into a local directory.
download(gallery_id: int, path: str = "downloaded", metadata: bool = False) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
gallery_id |
int |
— | Gallery ID from the URL (nhentai.net/g/<id>) |
path |
str |
"downloaded" |
Destination directory. A subfolder named after the gallery title is created inside |
metadata |
bool |
False |
If True, saves a metadata.txt alongside the images |
If the destination folder already exists, the download is aborted to avoid conflicts.
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked or rate limited by nhentai. Returns True once the gallery has been downloaded, False if the destination directory already existed.
download(123456)
download(123456, path="my_folder", metadata=True)
Downloads all galleries under a tag, sorted by date.
tag_download(tag: str, metadata: bool = False) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
tag |
str |
— | Tag name from the URL (nhentai.net/tag/<tag>) |
metadata |
bool |
False |
If True, saves metadata.txt for each gallery |
Waits 15–50 seconds between listing pages to avoid rate limiting. On large tags with many pages, this can take a long time.
Raises GalleryNotFoundError if the tag does not exist, RequestBlockedError if the request was blocked. Returns True once all galleries under the tag have been downloaded.
tag_download("tag-name")
tag_download("tag-name", metadata=True)
Downloads all galleries by an artist, sorted by date.
artist_download(artist: str, metadata: bool = False) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
artist |
str |
— | Artist name from the URL (nhentai.net/artist/<artist>) |
metadata |
bool |
False |
If True, saves metadata.txt for each gallery |
Waits 15–50 seconds between listing pages to avoid rate limiting.
Raises GalleryNotFoundError if the artist does not exist, RequestBlockedError if the request was blocked. Returns True once all galleries from the artist have been downloaded.
artist_download("artist-name")
Downloads all galleries featuring a character, sorted by date.
character_download(character: str, metadata: bool = False) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
character |
str |
— | Character name from the URL (nhentai.net/character/<character>) |
metadata |
bool |
False |
If True, saves metadata.txt for each gallery |
Waits 15–50 seconds between listing pages to avoid rate limiting.
Raises GalleryNotFoundError if the character does not exist, RequestBlockedError if the request was blocked. Returns True once all galleries featuring the character have been downloaded.
character_download("character-name")
Downloads all galleries under a parody, sorted by date.
parody_download(parody: str, metadata: bool = False) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
parody |
str |
— | Parody name from the URL (nhentai.net/parody/<parody>) |
metadata |
bool |
False |
If True, saves metadata.txt for each gallery |
Waits 15–50 seconds between listing pages to avoid rate limiting.
Raises GalleryNotFoundError if the parody does not exist, RequestBlockedError if the request was blocked. Returns True once all galleries under the parody have been downloaded.
parody_download("parody-name")
Extracts all metadata from a gallery and returns it as a dictionary.
extract_metadata(gallery_id: int) -> dict
Returns:
| Key | Type | Description |
|---|---|---|
"title" |
str |
Gallery title |
"gallery id" |
int |
Gallery ID |
"parodies" |
list[str] |
Parodies |
"characters" |
list[str] |
Characters |
"tags" |
list[str] |
Tags |
"artists" |
list[str] |
Artists |
"groups" |
list[str] |
Groups |
"languages" |
list[str] |
Languages |
"categories" |
list[str] |
Categories |
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked or rate limited.
from nhentai_tools import extract_metadata
meta = extract_metadata(123456)
Writes a metadata dictionary into metadata.txt inside a directory.
embed_metadata(metadata: dict, path: str) -> None
| Parameter | Type | Description |
|---|---|---|
metadata |
dict |
Dictionary from extract_metadata()
|
path |
str |
Directory where metadata.txt will be written |
from nhentai_tools import extract_metadata, embed_metadata
meta = extract_metadata(123456)
embed_metadata(meta, path="downloaded/Gallery-Title")
As of v1.1.0, extraction and download functions no longer return -1 or None on error. They raise exceptions instead:
| Exception | Raised when |
|---|---|
GalleryNotFoundError |
The requested gallery, tag, artist, character or parody does not exist (HTTP 404) |
RequestBlockedError |
The request was blocked or rate limited by nhentai (HTTP 403 / 429) |
from nhentai_tools import extract_title, GalleryNotFoundError, RequestBlockedError
try:
title = extract_title(999999999)
except GalleryNotFoundError:
print("This gallery doesn't exist.")
except RequestBlockedError:
print("Blocked or rate limited, try again later.")Both exceptions expose a .message attribute and format to that message when printed.
To reduce the chance of getting blocked by nhentai:
- All single-gallery
extract_*functions (tags, characters, languages, categories, artists, parodies, groups) wait a random 1–3 second interval before making their request. - Mass download functions (
tag_download,artist_download,character_download,parody_download) additionally wait 15–50 seconds between listing pages.
This is automatic and not currently configurable. Because of it, mass downloads over listings with many pages will take noticeably longer than a single download() call.
extract_title(gallery_id: int) -> str
Returns the gallery title with spaces replaced by hyphens.
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked or rate limited (HTTP 403/429).
extract_tags(gallery_id: int) -> list[str]
Returns a list of tags.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting (see Rate limit protection).
extract_artists(gallery_id: int) -> list[str]
Returns a list of artists.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_characters(gallery_id: int) -> list[str]
Returns a list of characters.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_parodies(gallery_id: int) -> list[str]
Returns a list of parodies.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_groups(gallery_id: int) -> list[str]
Returns a list of groups.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_languages(gallery_id: int) -> list[str]
Returns a list of languages.
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_categories(gallery_id: int) -> list[str]
Returns a list of categories (e.g. doujinshi, manga).
Raises GalleryNotFoundError / RequestBlockedError on error. Waits 1–3 seconds before requesting.
extract_number_of_pages(gallery_id: int) -> int
Returns the total number of pages in the gallery.
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked.
extract_server(gallery_id: int) -> str
Returns the CDN server URL where the gallery's images are hosted (e.g. https://i3.nhentai.net/).
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked.
extract_gallery_server_id(gallery_id: int) -> int
Returns the internal server-side ID used to locate images on the CDN.
nhentai galleries have two IDs: the public one in the URL (
nhentai.net/g/<id>) and an internal server-side ID used for CDN image storage. This function returns the latter.
Raises GalleryNotFoundError if the gallery does not exist, RequestBlockedError if the request was blocked.