# heic-decode

> Decode HEIC images to raw data

Latest version **2.1.0** (published 2025-07-04) · ISC license · 0 weekly downloads

## Install

```sh
npm install heic-decode
pnpm add heic-decode
yarn add heic-decode
bun add heic-decode
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-07-04 |
| First published | 2020-01-18 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | separate (@types/heic-decode) |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 1 |
| Unpacked size | 6.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 59 |
| Author | Kiril Vatev |
| Maintainers | kirilv |
| Keywords | heic, heif, image, photo, decode |

## Links

- npm: https://www.npmjs.com/package/heic-decode
- Repository: https://github.com/catdad-experiments/heic-decode
- Homepage: https://github.com/catdad-experiments/heic-decode#readme
- Issues: https://github.com/catdad-experiments/heic-decode/issues
- npm.io page: https://npm.io/package/heic-decode

## Dependencies (1)

- [libheif-js](https://npm.io/package/libheif-js.md) ^1.19.8

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads
- [datasets-fi-postalcodes](https://npm.io/package/datasets-fi-postalcodes.md) — 1.1K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2025-07-04
- 2.0.0 — 2023-11-09
- 1.1.2 — 2020-12-21
- 1.1.1 — 2020-02-04
- 1.1.0 — 2020-02-01
- 1.0.2 — 2020-02-01
- 1.0.1 — 2020-01-18
- 1.0.0 — 2020-01-18

## README

# heic-decode

> Decode HEIC images to extract raw pixel data.

[![CI][ci.svg]][ci.link]
[![npm-downloads][npm-downloads.svg]][npm.link]
[![npm-version][npm-version.svg]][npm.link]

[ci.svg]: https://github.com/catdad-experiments/heic-decode/actions/workflows/ci.yml/badge.svg
[ci.link]: https://github.com/catdad-experiments/heic-decode/actions/workflows/ci.yml
[npm-downloads.svg]: https://img.shields.io/npm/dm/heic-decode.svg
[npm.link]: https://www.npmjs.com/package/heic-decode
[npm-version.svg]: https://img.shields.io/npm/v/heic-decode.svg

## Install

```bash
npm install heic-decode
```

## Usage

Decode the main image in the file:

```javascript
const fs = require('fs');
const { promisify } = require('util');
const decode = require('heic-decode');

(async () => {
  const buffer = await promisify(fs.readFile)('/path/to/my/image.heic');
  const {
    width,  // integer width of the image
    height, // integer height of the image
    data    // Uint8ClampedArray containing pixel data
  } = await decode({ buffer });
})();
```

Decode all images in the file:

```javascript
const fs = require('fs');
const { promisify } = require('util');
const decode = require('heic-decode');

(async () => {
  const buffer = await promisify(fs.readFile)('/path/to/my/multi-image.heic');
  const images = await decode.all({ buffer });

  for (let image of images) {
    // decode and use each image individually
    // so you don't run out of memory
    const {
      width,  // integer width of the image
      height, // integer height of the image
      data    // Uint8ClampedArray containing pixel data
    } = await image.decode();
  }

  // when you are done, make sure to free all memory used to convert the images
  images.dispose();
})();
```

> Note: when decoding a single image (i.e. using `decode`), all resources are freed automatically after the conversion. However, when decoding all images in a file (i.e. using `decode.all`), you can decode the images at any time, so there is no safe time for the library to free resources -- you need to make sure to call `dispose` once you are done.

When the images are decoded, the return value is a plain object in the format of [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData). You can use this object to integrate with other imaging libraries for processing.

_Note that while the decoder returns a Promise, it does the majority of the work synchronously, so you should consider using a worker thread in order to not block the main thread in highly concurrent production environments._

## Related

* [heic-cli](https://github.com/catdad-experiments/heic-cli) - convert heic/heif images to jpeg or png from the command line
* [heic-convert](https://github.com/catdad-experiments/heic-convert) - convert heic/heif images to jpeg and png
* [libheif-js](https://github.com/catdad-experiments/libheif-js) - libheif as a pure-javascript npm module

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