Imagedl: Search and download images from specific websites. (轻量级美食/动植物昆虫真菌/建筑/自然/动漫二次元/高清摄影/宇宙天文/网络图片搜索下载器，支持谷歌，百度，必应，NASA，360，Pixabay，Yandex，搜狗，雅虎，DuckDuckGo，Unsplash，Safebooru，Gelbooru，Danbooru，次元小镇，花瓣网，Foodiesfeed， Everypixel，微博，iNaturalist等各大平台，轻松构建大模型训练测试集)
imagedl 以其跨平台的支持能力、灵活的抓取需求设置和简洁的 API 接口成为了一款极其实用的图像资源搜集工具。它的价值在于填补了现有开源项目在功能兼容性与多样性上的不足。尽管在数据存储管理及安全合规性方面仍有提升空间，但其在图像资源获取上的流畅体验足以让开发者、科研人员和爱好者们体会到它的高效与便捷。
2026-11-07: Released pyimagedl v0.5.6 — performed routine monthly maintenance on all image clients and fixed several bugs in the Danbooru and Dimtown image clients.
2026-10-23: Released pyimagedl v0.5.5 — performed monthly routine maintenance on all image clients and fixed six: Yandex, Unsplash, Metropolitan, Wellcome, PicJumbo, and DuckDuckGo.
2026-09-19: Released pyimagedl v0.5.4 — perform monthly maintenance checks on the image clients; this update fixes the Yahoo and Sogou image clients.
📘 Introduction
⚡ Imagedl is a lightweight image search and download tool designed for efficient large-scale image collection from specific websites.
It supports multiple major sources, including Google, Baidu, Bing, 360, Pixabay, Yandex, Sogou, Yahoo, DuckDuckGo, Unsplash, Safebooru, Gelbooru, Danbooru, Huaban, Foodiesfeed, Everypixel, Weibo, and more.
With support for diverse content such as web images, food, animals, architecture, nature, anime-style artwork, and high-resolution photography, Imagedl is well suited for constructing training and testing datasets for large models.
If you find it useful, please star the repository ⭐ to support development and keep up with future updates.
You have three installation methods to choose from,
# from pip
pip install pyimagedl
# from github repo method-1
pip install git+https://github.com/CharlesPikachu/imagedl.git@main
# from github repo method-2
git clone https://github.com/CharlesPikachu/imagedl.git
cd imagedl
python setup.py install
Please note that some image sources need to be crawled using DrissionPage, such as EverypixelImageClient and GoogleImageClient.
If DrissionPage cannot find a suitable browser in the current environment, it will automatically download the latest compatible beta version of Google Chrome for the current system.
So if you notice that the program is downloading a browser, there is no need to be overly concerned.
⚡ Quick Start
imagedl is built around imagedl.ImageClient.
In the current implementation, ImageClient accepts one or more sources through image_sources, and lets you configure each source with init_image_clients_cfg, clients_threadings, requests_overrides, and search_filters.
When no source is specified, the default source is BaiduImageClient.
The simplest working example
Start with one source like "BaiduImageClient" and "BingImageClient" and a small search limit. This is the easiest way to confirm that your environment is set up correctly.
import random
from imagedl import imagedl
client = imagedl.ImageClient(image_sources=["BaiduImageClient"], init_image_clients_cfg={})
search_results = client.search(keyword="cute cats", search_limits_per_source=10)
downloaded_results = client.download(image_infos=search_results)
print(f"found {sum(len(v) for v in search_results.values())} items")
print(f"downloaded {len(downloaded_results)} items")
print('random example >>> ')
print(random.choice(downloaded_results))
In the current API, search() returns a dictionary whose keys are source names and whose values are lists of ImageInfo objects. The updated download() method can now accept either:
the original dictionary returned by search()
a flat list of ImageInfo objects
So the normal workflow is now simply: search -> download
CLI options
The package also defines a command-line interface with these main options:
Usage: imagedl [OPTIONS]
Options:
--version Show the version and exit.
-k, --keyword TEXT The keywords for the image search. If left
empty, an interactive terminal will open
automatically.
-s, --image-sources, --image_sources TEXT
The image search and download sources.
[default: BaiduImageClient]
-c, --init-image-clients-cfg, --init_image_clients_cfg TEXT
Config such as `work_dir` for each image
client as a JSON string.
-o, --requests-overrides, --requests_overrides TEXT
Requests.get / Requests.post kwargs such as
`headers` and `proxies` for each image
client as a JSON string.
-t, --clients-threadings, --clients_threadings TEXT
Number of threads used for each image client
as a JSON string.
-f, --search-filters, --search_filters TEXT
Search filters for each image client as a
JSON string.
-l, --search-limits-per-source, --search_limits_per_source INTEGER RANGE
Scale of image downloads. [default: 1000;
1<=x<=100000000.0]
--help Show this message and exit.
The demonstration of running imagedl -k "猫咪" -s "BaiduImageClient" -l 1000 is as follows,
What happens during search and download
Each source searches independently, using its own thread count, request overrides, and filters.
During searching, duplicate items are removed, and each result is assigned a unique save path automatically.
During downloading, the package groups results by source, tries the candidate image URLs one by one, detects the real file extension from the downloaded content, and then saves the file.
Where files are saved
By default, files are saved under imagedl_outputs. The actual folder structure is:
The search stage writes search_results.pkl, and the download stage writes download_results.pkl.
Image filenames are numbered automatically, and the extension is added after the file content is successfully recognized.
Main arguments of ImageClient
The most important arguments are:
image_sources: a string or list of source names, such as "BaiduImageClient" or ["BaiduImageClient", "DuckduckgoImageClient"]
init_image_clients_cfg: per-source initialization settings such as work_dir, max_retries, maintain_session, cookies, and curl-cffi-related options
clients_threadings: per-source thread counts used for search and download
requests_overrides: per-source request arguments such as custom headers or proxies
search_filters: per-source filter settings
search_limits_per_source: the number of images to search for each source when calling search()
Internally, each source is initialized with defaults such as work_dir="imagedl_outputs", max_retries=5, maintain_session=False, auto_set_proxies=False, random_update_ua=False, logger_handle=LoggerHandle() and disabled curl-cffi options unless you override them.
Save images to a custom folder
You can set a different output folder for each source through init_image_clients_cfg.
This is the recommended way to control where your files are saved.
Search from multiple sources
You can search several sources at once. In that case, it is usually best to configure thread count and output directory per source.
Here is a simple example:
The package forwards these values to the underlying request calls for that source.
A simple way to use one source directly
If you only want to test or use a single website, you can import a concrete source client directly from imagedl.modules.sources. This is a very simple and beginner-friendly way to start.
评论