img-dl

img-dl

Downloade image(s), by command or programmatically. The alternative for image-downloader package (see the comparison).

Prerequisites

• Node.js 18 or later
• npm 9 or later

Installation

img-dl can be installed in the global scope (if you'd like to have it available and use it on the whole system) or locally for a specific package (especially if you'd like to use it programmatically):

Install globally:

npm install -g img-dl

Install locally:

npm install img-dl

Usage

Command line

Access the help page with imgdl --help

Download image(s), by command or programmatically

USAGE
  $ imgdl <url> ... [OPTIONS]

PARAMETERS
  url   The URL of the image to download. Provide multiple URLs to download multiple images.
        In increment mode, the URL must contain {i} placeholder for the index,
        only one URL is allowed, and the 'end' flag is required.

OPTIONS
  -d, --dir=<path>          The output directory. Default: current working directory
      --end=<number>        The end index. Required in increment mode
  -e, --ext=<ext>           The file extension. Default: original extension or jpg
  -h, --help                Show this help message
  -H, --header=<header>     The header to send with the request. Can be used multiple times
  -i, --increment           Enable increment mode. Default: false
      --interval=<number>   The interval between each batch of requests in milliseconds
  -n, --name=<filename>     The filename. Default: original filename or timestamp
      --max-retry=<number>  Set the maximum number of times to retry the request if it fails
      --silent              Disable logging
      --start=<number>      The start index for increment mode. Default: 0
      --step=<number>       The number of requests to make at the same time. Default: 5
  -t, --timeout=<number>    Set timeout for each request in milliseconds
  -v, --version             Show the version number

EXAMPLES
  $ imgdl https://example.com/image.jpg
  $ imgdl https://example.com/image.jpg --dir=images --name=example --ext=png
  $ imgdl https://example.com/image.jpg --silent
  $ imgdl https://example.com/image.jpg https://example.com/image2.webp
  $ imgdl https://example.com/image-{i}.jpg --increment --start=1 --end=10
  $ imgdl https://example.com/image.jpg --header="User-Agent: Mozilla/5.0" --header="Cookie: foo=bar"

Simple download

imgdl https://example.com/image.jpg

Download multiple images

imgdl https://example.com/image.jpg https://example.com/image2.jpg

Download multiple images with increment mode

imgdl https://example.com/image-{i}.jpg --increment --start=1 --end=10

Programmatically

Simple download

import imgdl from 'img-dl';

const image = await imgdl('https://example.com/image.jpg');
console.log(image);
/*
{
  url: 'https://example.com/image.jpg',
  name: 'image',
  extension: 'jpg',
  directory: '/path/to/current/working/directory',
  originalName: 'image',
  originalExtension: 'jpg',
  path: '/path/to/current/working/directory/image.jpg',
}
*/

Download multiple images

import imgdl from 'img-dl';

const images = await imgdl([
  'https://example.com/image.jpg',
  'https://example.com/image2.jpg',
]);

API

imgdl(url, ?options)

Download image(s) from the given URL(s).

url

Type: string | string[]
Required: true

The URL(s) of the image(s) to download. Required.

options

Type: Options
Required: false

Properties	Type	Default	Description
directory	string	process.cwd()	The output directory
extension	string	jpg	The file extension. If not specified, the original extension will be used. If the original extension is not available, 'jpg' will be used.
headers	Record<string, string | string[] | undefined>	undefined	The headers to send with the request.
interval	number	100	The interval between each batch of requests in milliseconds when downloading multiple images.
name	string	image	The filename. If not specified, the original filename will be used. If the original filename is not available, 'image' will be used. When downloading multiple images, -index will be appended to the end of the name (suffix). index will start from 1. For example: 'image-1'
maxRetry	number	2	Set the maximum number of times to retry the request if it fails.
onSuccess	(image: Image) => void	undefined	The callback function to be called when the image is successfully downloaded. Only available when downloading multiple images.
onError	(error: Error, url: string) => void	undefined	The callback function to be called when the image fails to download. Only available when downloading multiple images.
signal	AbortSignal | undefined	The signal to abort the request.
step	number	5	The number of requests to make at the same time when downloading multiple images.
timeout	number	undefined	Set timeout for each request in milliseconds.

Comparison

Features	img-dl	image-downloader
Download single image	✅	✅
Download multiple images	✅	❌
CLI	✅	❌
Increment download	✅	❌
Custom filename	✅	✅
Custom extension	✅	❌
Request timeout	✅	✅
Retry failed request	✅	❌

Support This Project

Give a ⭐️ if this project helped you!

You can support this project by donating via GitHub Sponsors, Trakteer, or Saweria.