Documentation

Downloading

download()

Downloads all images from a gallery into a local directory.

download(gallery_id: int, path: str = "downloaded", metadata: bool = False)

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.

download(123456)
download(123456, path="my_folder", metadata=True)

---

tag_download()

Downloads all galleries under a tag, sorted by today's popularity.

tag_download(tag: str, metadata: bool = False)

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

tag_download("tag-name")
tag_download("tag-name", metadata=True)

---

artist_download()

Downloads all galleries by an artist, sorted by date.

artist_download(artist: str, metadata: bool = False)

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

artist_download("artist-name")

---

character_download()

Downloads all galleries featuring a character, sorted by date.

character_download(character: str, metadata: bool = False)

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

character_download("character-name")

---

parody_download()

Downloads all galleries under a parody, sorted by date.

parody_download(parody: str, metadata: bool = False)

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

parody_download("parody-name")

---

Metadata

extract_metadata()

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

from nhentai_tools import extract_metadata

meta = extract_metadata(123456)

---

embed_metadata()

Writes a metadata dictionary into metadata.txt inside a directory.

embed_metadata(metadata: dict, path: str)

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")

---

Extraction

extract_title()

extract_title(gallery_id: int) -> str

Returns the gallery title with spaces replaced by hyphens. Returns -1 on HTTP 403.

---

extract_tags()

extract_tags(gallery_id: int) -> list[str]

Returns a list of tags.

---

extract_artists()

extract_artists(gallery_id: int) -> list[str]

Returns a list of artists.

---

extract_characters()

extract_characters(gallery_id: int) -> list[str]

Returns a list of characters.

---

extract_parodies()

extract_parodies(gallery_id: int) -> list[str]

Returns a list of parodies.

---

extract_groups()

extract_groups(gallery_id: int) -> list[str]

Returns a list of groups.

---

extract_languages()

extract_languages(gallery_id: int) -> list[str]

Returns a list of languages.

---

extract_categories()

extract_categories(gallery_id: int) -> list[str]

Returns a list of categories (e.g. doujinshi, manga).

---

extract_number_of_pages()

extract_number_of_pages(gallery_id: int) -> int

Returns the total number of pages in the gallery.

---

extract_server()

extract_server(gallery_id: int) -> str

Returns the CDN server URL where the gallery's images are hosted (e.g. https://i3.nhentai.net/).

---

extract_gallery_server_id()

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.

Returns -1 on HTTP 403, None if the ID cannot be parsed.