Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 544 Commits
.circleci		.circleci
.github/workflows		.github/workflows
.vscode		.vscode
.yarn/plugins/@yarnpkg		.yarn/plugins/@yarnpkg
bin		bin
lib		lib
specs		specs
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc.yaml		.prettierrc.yaml
.yarnrc.yml		.yarnrc.yml
Contributors.md		Contributors.md
LICENSE		LICENSE
Readme.md		Readme.md
biome.json		biome.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
tsup.config.ts		tsup.config.ts
yarn.lock		yarn.lock

Repository files navigation

image-size

Fast, lightweight NodeJS package to get dimensions of any image file or buffer.

Key Features

Zero dependencies
Supports all major image formats
Works with both files and buffers
Minimal memory footprint - reads only image headers
ESM and CommonJS support
TypeScript types included

Supported formats

BMP
CUR
DDS
GIF
HEIC (HEIF, AVCI, AVIF)
ICNS
ICO
J2C
JPEG-2000 (JP2)
JPEG
JPEG-XL
KTX (1 and 2)
PNG
PNM (PAM, PBM, PFM, PGM, PPM)
PSD
SVG
TGA
TIFF
WebP

Installation

npm install image-size# oryarn add image-size# orpnpm add image-size

Usage

Passing in a Buffer/Uint8Array

Best for streams, network requests, or when you already have the image data in memory.

import{imageSize}from'image-size'// orconst{ imageSize}=require('image-size')constdimensions=imageSize(buffer)console.log(dimensions.width,dimensions.height)

Reading from a file

Best for local files. Returns a promise.

import{imageSizeFromFile}from'image-size/fromFile'// orconst{ imageSizeFromFile}=require('image-size/fromFile')constdimensions=awaitimageSizeFromFile('photos/image.jpg')console.log(dimensions.width,dimensions.height)

Note: Reading from files has a default concurrency limit of100To change this limit, you can call thesetConcurrency function like this:

import{setConcurrency}from'image-size/fromFile'// orconst{ setConcurrency}=require('image-size/fromFile')setConcurrency(123456)

Reading from a file Syncronously (not recommended)⚠️

v1.x of this library had a sync API, that internally used sync file reads.

This isn't recommended because this blocks the node.js main thread, which reduces the performance, and prevents this library from being used concurrently.

However if you still need to use this package syncronously, you can read the file syncronously into a buffer, and then pass the buffer to this library.

import{readFileSync}from'node:fs'import{imageSize}from'image-size'constbuffer=readFileSync('photos/image.jpg')constdimensions=imageSize(buffer)console.log(dimensions.width,dimensions.height)

3. Command Line

Useful for quick checks.

npx image-size image1.jpg image2.png

Multi-size

If the target file/buffer is an HEIF, an ICO, or a CUR file, thewidth andheight will be the ones of the largest image in the set.

An additionalimages array is available and returns the dimensions of all the available images

import{imageSizeFromFile}from'image-size/fromFile'// orconst{ imageSizeFromFile}=require('image-size/fromFile')const{ images}=awaitimageSizeFromFile('images/multi-size.ico')for(constdimensionsofimages){console.log(dimensions.width,dimensions.height)}

Using a URL

importurlfrom'node:url'importhttpfrom'node:http'import{imageSize}from'image-size'constimgUrl='http://my-amazing-website.com/image.jpeg'constoptions=url.parse(imgUrl)http.get(options,function(response){constchunks=[]response.on('data',function(chunk){chunks.push(chunk)}).on('end',function(){constbuffer=Buffer.concat(chunks)console.log(imageSize(buffer))})})

Disabling certain image types

import{disableTypes}from'image-size'// orconst{ disableTypes}=require('image-size')disableTypes(['tiff','ico'])

JPEG image orientation

If the orientation is present in the JPEG EXIF metadata, it will be returned by the function. The orientation value is anumber between 1 and 8 representing a type of orientation.

import{imageSizeFromFile}from'image-size/fromFile'// orconst{ imageSizeFromFile}=require('image-size/fromFile')const{ width, height, orientation}=awaitimageSizeFromFile('images/photo.jpeg')console.log(width,height,orientation)

Limitations

Partial File Reading
- Only reads image headers, not full files
- Some corrupted images might still report dimensions
SVG Limitations
- Only supports pixel dimensions and viewBox
- Percentage values not supported
File Access
- Reading from files has a default concurrency limit of 100
- Can be adjusted usingsetConcurrency()
Buffer Requirements
- Some formats (like TIFF) require the full header in buffer
- Streaming partial buffers may not work for all formats