# image-hash

> Create a hash from an image

Latest version **8.1.1** (published 2026-11-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install image-hash
pnpm add image-hash
yarn add image-hash
bun add image-hash
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.1.1 |
| Published | 2026-11-07 |
| First published | 2017-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 4 |
| Unpacked size | 28.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 41 |
| Author | Daniel Morrison |
| Maintainers | danm |
| Keywords | phash, hash, image hash, perceptual hash |

## Links

- npm: https://www.npmjs.com/package/image-hash
- Repository: https://github.com/danm/image-hash
- Homepage: https://github.com/danm/image-hash#readme
- Issues: https://github.com/danm/image-hash/issues
- npm.io page: https://npm.io/package/image-hash

## Dependencies (4)

- [pngjs](https://npm.io/package/pngjs.md) ^7.0.0
- [jpeg-js](https://npm.io/package/jpeg-js.md) ^0.4.4
- [file-type](https://npm.io/package/file-type.md) ^22.2.0
- [@cwasm/webp](https://npm.io/package/@cwasm/webp.md) ^0.1.5

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 8.1.1 (latest) — 2026-11-07
- 8.0.1 — 2026-10-26
- 7.0.1 — 2025-11-13
- 6.0.3 — 2025-11-13
- 6.0.2 — 2025-11-13
- 6.0.1 — 2025-09-25
- 5.3.2 — 2023-09-04
- 5.3.1 — 2022-05-03
- 5.2.1 — 2022-05-03
- 5.0.2 — 2022-02-02
- 5.0.1 — 2022-01-21
- 4.0.1 — 2020-08-01
- 3.5.1 — 2019-10-29
- 3.4.1 — 2019-10-29
- 3.3.9 — 2019-08-02
- … 21 more at https://npm.io/package/image-hash/versions

## README

# image-hash

A wrapper around [block-hash](https://github.com/commonsmachinery/blockhash-js) to easily hash a local or remote file with Node.

Supports JPG, PNG and WebP

## Install

```bash
npm i image-hash
```

Requires Node.js 22.12 or later.

### Bundling

WebP images are decoded with [@cwasm/webp](https://github.com/LinusU/cwasm-webp), a WebAssembly build of libwebp, which reads `webp.wasm` from its package folder. It is only loaded the first time a WebP image is hashed, so JPEG and PNG images work in a bundle (e.g. esbuild or webpack) as they are. To hash WebP images from a bundle, copy `node_modules/@cwasm/webp/webp.wasm` next to the bundled file.

## Use

`imageHash` returns a promise that resolves to the hash as a hex string.

```javascript
import { readFile } from 'node:fs/promises';
import { imageHash } from 'image-hash';

// local file
const hash = await imageHash('./_95695590_tv039055678.jpg', 16, true);
console.log(hash);
// 0773063f063f36070e070a070f378e7f1f000fff0fff020103f00ffb0f810ff0

// bits and precise are optional, and default to 16 and true
await imageHash('./_95695590_tv039055678.jpg');

// remote file
await imageHash('https://ichef-1.bbci.co.uk/news/660/cpsprodpb/7F76/production/_95703623_mediaitem95703620.jpg', 16, true);

// remote file with fetch options
await imageHash({
  url: 'https://ichef-1.bbci.co.uk/news/660/cpsprodpb/7F76/production/_95703623_mediaitem95703620.jpg',
  headers: { authorization: 'Bearer token' },
  signal: AbortSignal.timeout(10_000),
}, 16, true);

// Buffer
const data = await readFile('./_95695591_tv039055678.jpeg');
await imageHash(data, 16, true);

// Buffer, with mime type and file name
await imageHash({ ext: 'image/jpeg', data, name: 'photo.jpeg' }, 16, true);
```

Errors (file not found, unsupported image type, failed requests) reject the promise, so use `try`/`catch` or `.catch()`.

```javascript
try {
  await imageHash('./missing.jpg');
} catch (error) {
  console.error(error);
}
```

The package is ESM, but CommonJS projects can still `require` it:

```javascript
const { imageHash } = require('image-hash');

imageHash('./_95695590_tv039055678.jpg').then((hash) => console.log(hash));
```

## API

```typescript
imageHash(src: string | Buffer | UrlRequestObject | BufferObject, bits?: number, precise?: boolean): Promise<string>
```

| Argument | Type | Description | Default | Example |
| -------- | ---- | ----------- | ------- | ------- |
| src | `string`, `Buffer` or `object` | A file path, an `http(s)` URL, a `Buffer`, a request object with a remote `url`, or a buffer object (see below) | Required | `'./image.jpg'` |
| bits | `number` | The number of bits in a row. The more bits, the more unique the hash. Must be a positive integer. | `16` | `8` |
| precise | `boolean` | Whether a precision algorithm is used. `true` Precise but slower, non-overlapping blocks. `false` Quick and crude, non-overlapping blocks. Method 2 is recommended as a good tradeoff between speed and good matches on any image size. The quick ones are only advisable when the image width and height are an even multiple of the number of blocks used. | `true` | `false` |

### Source Object Types

```typescript
// Request object. Any other fetch options (headers, signal, ...) are passed to fetch.
interface UrlRequestObject extends RequestInit {
  url: string;
}

// Buffer object
interface BufferObject {
  ext?: string; // mime type of the image, detected from the data if omitted
  data: Buffer;
  name?: string; // file name, used to check the extension matches the mime type
}
```

## Settings

Image hash will log out warnings if environment variable `VERBOSE` is set.

## Upgrading from v7

- The callback argument has been removed. `imageHash` now returns a promise.
- `bits` and `precise` are optional.
- A `Buffer` can be passed directly.
- The package is now ESM and requires Node.js 22.12 or later.

## Development

Built with TypeScript, ESLint and Vitest, using pnpm.

```bash
pnpm install
pnpm test
pnpm run lint
pnpm run typecheck
pnpm run build
```

## Publishing

Every push to `master` stages a new patch version on npm. The CI workflow bumps the patch version, stages it with `npm stage publish`, then pushes the version commit and tag back to `master`. The version goes live once a maintainer approves it on npm with 2FA. For a major or minor release, set `version` in `package.json` to the version before the one you want, e.g. `9.0.0` to publish `9.0.1`.

Staging uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored in GitHub. It is configured on npmjs.com under the package's Settings → Trusted Publisher, with the GitHub repository `danm/image-hash`, the workflow file `ci.yml`, and only staged publishing allowed.

## Credit

The hard bit of this comes with thanks from [commonsmachinery](https://github.com/commonsmachinery) for [blockhash-js](https://github.com/commonsmachinery/blockhash-js)

## License

Distributed under an MIT license

---
_Source: https://npm.io/package/image-hash · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
