Usage
Installation
Quick start
Demos
API
Perf
Changelog
FAQ
Contributing
demo page & playground .
Features
Works everywhere, parses anything you throw at it.
* 🏎️
Fastest EXIF lib : +-1ms per file
* 🗃️
Any input : buffers, url, <img> tag, and more
* 📷 Files:
.jpg ,
.tif ,
.png ,
.heic , .avif, .iiq
* 🔎 Segments:
TIFF (EXIF, GPS, etc...),
XMP ,
ICC ,
IPTC , JFIF, IHDR
* 📑
Reads only first few bytes
* 🔬
Skips parsing tags you don't need
* ✨
Isomorphic : Browser & Node.js
* 🗜️
No dependencies
* 🖼️ Extracts thumbnail
* 💔 Salvages broken files
* 🧩 Modular
* 📚 Customizable tag dictionaries
* 📦 Bundled as UMD/CJS or ESM
* ✔ Tested and benchmarked
* 🤙 Promises
* 🕸 Supports even ~IE11~
IE10
and more (click to expand)
XMP Parser - minimalistic, reliable, without dependencies
XMP Extended
Multi-segment ICC
Extracts all ICC tags (RedMatrixColumn, GreenTRC, B2A2, etc...)
TIFF dictionaries contain less frequently used, non-standard and proprietary TIFF/EXIF tags (only in full bundle)
Handles UCS2 formatted strings (XPTitle tag), instead of leaving it as a buffer
Normalizes strings
Revives dates into Date class instances
Converts GPS coords from DMS to DD format. From GPSLatitude, GPSLatitudeRef tags ([50, 17, 58.57] & "N") to single latitude value (50.29960).
Instructs how to rotate photo with exifr.rotation() and accounts for quirky autorotation behavior of iOs Safari and Chrome 81 and newer
You don't need to read the whole file to tell if there's EXIF in it. And you don't need to extract all the data when you're looking for just a few tags. Exifr just jumps through the file structure, from pointer to pointer. Instead of reading it byte by byte, from beginning to end.
Exifr does what no other JS lib does. It's
efficient and
blazing fast !
| Segments | JPEG | TIFF / IIQ | HEIF (HEIC, AVIF) | PNG |
|-|-|-|-|-|
| EXIF/TIFF, GPS | ✔ | ✔ | ✔ | ✔ |
| XMP | ✔ | ✔ | ❌ | ✔ |
| IPTC | ✔ | ✔ | ❌ | 🟡
(If it's a part of IHDR) |
| ICC | ✔ | ✔ | ✔ | ✔
(Node.js only, requires zlib) |
| Thumbnail | ✔ | ❌ | ❌ | ❌ |
| JFIF
(JPEG header) | ✔ | ⚫ | ⚫ | ⚫ |
| IHDR
(PNG header) | ⚫ | ⚫ | ⚫ | ✔ |
Usage
file
can be any binary format (Buffer
, Uint8Array
, Blob
and more), element, string path or url.
options
specify what segments and blocks to parse, filters what tags to pick or skip.
exifr.parse(file)
|object
|Parses IFD0, EXIF, GPS blocks|
exifr.parse(file, true)
|object
|Parses everything|
exifr.parse(file, ['Model', 'FNumber', ...])
|object
|Parses only specified tags|
exifr.parse(file, {options})
|object
|Custom settings|
exifr.gps(file)
|{latitude, longitude}
|Parses only GPS coords|
exifr.orientation(file)
|number
|Parses only orientation|
exifr.rotation(file)
|object
|Info how to rotate the photo|
exifr.thumbnail(file)
|Buffer\|Uint8Array
binary|Extracts embedded thumbnail|
exifr.thumbnailUrl(file)
|string
Object URL|Browser only|
exifr.sidecar(file)
|object
|Parses sidecar file|
Installation
`
`
full
and then scale down to lite
, mini
, or better yet, build your own around modular core.
`
js
`
`
html
`
Browsers : lite
and mini
are recommended because of balance between features and file size. UMD format attaches the library to global window.exifr
object.
IE & old browsers: legacy
builds come bundled with polyfills. Learn more .
full - Contains everything. Intended for use in Node.js.
lite - Reads JPEG and HEIC. Parses TIFF/EXIF and XMP.
mini - Stripped down to basics. Parses most useful TIFF/EXIF from JPEGs. Has no tag dictionaries .
full
version in browser, or use any other build in Node.js.
ESM - Modern syntax for use in modern browsers and Node.js .
import
syntax.
UMD - Universal format for browsers and Node.js.
require('exifr')
, AMD/RequireJS and global window.exifr
.
legacy UMD - For use in older browsers (up to IE10).
Promise
polyfill. Learn more here .
Detailed comparison (click to expand)
+ Node.js )Browser only ) | BlobReader | none |
.jpg .heic
.tif/ .iiq
.png | .jpg
.heic | .jpg
| none |
full.esm.js
full.esm.mjs
full.umd.js
full.umd.cjs
full.legacy.umd.js
| lite.esm.js
lite.esm.mjs
lite.umd.js
lite.umd.cjs
lite.legacy.umd.js
| mini.esm.js
mini.esm.mjs
mini.umd.js
mini.umd.cjs
mini.legacy.umd.js
| Learn more |
.mjs
and .js
for ESM. .cjs
and .js
for UMD. Pick one that works with your tooling or webserver.
(click to expand for more info)
.mjs
extension and modules with "type":"module"
in package.json. Turns out the "type":"module"
approach alone is not yet ready for production. Some bundlers and tools may work or break with .mjs
extension, whereas it's important for Node.js. The same applies to the new .cjs
extension (introduced in Node.js 13).
.mjs
extensions and transpiled to both ESM and UMD formats.
"main"
(field in package.json) entry point is now full.umd.cjs
but you can still use ESM by explicitly importing full.esm.mjs
. "module"
field (used by some tools) points to full.esm.mjs
.
.mjs
or .cjs
files you can use their identical .js
clone. For example full.esm.mjs
is identical to full.esm.js
. So is lite.esm.cjs
to lite.esm.js
. Just pick one that fits your tools or environment.
import * as exifr from 'exifr'
as well as import exifr from 'exifr'
(recommended).
Examples
`
js
`
`
js
`
`
js
`
`
js
`
`
js
`
`
html
`
`
html
`
$3
playground examples/thumbnail.html , code
examples/orientation.html , code
examples/depth-map-extraction.html , code
benchmark/gps-dnd.html , code
examples/worker.html , code
examples/legacy.html , code
benchmark/formats-reading.html , code
examples/ folder
API
$3
Promise
file (in any format), parses it and returns exif object. Optional options argument can be specified.
$3
Promise
Uses pick/skip filters and perf improvements to only extract latitude and longitude tags from GPS block. And to get GPS-IFD pointer it only scans through IFD0 without reading any other unrelated data.
examples/gps.js to learn more.
$3
Promise
$3
Promise
deg : angle in degrees (i.e. 180), useful for css transform: rotate()
rad : angle in radians (i.e. 3.141592653589793) useful for canvas' ctx.rotate()
scaleX : image is (-1) or isn't (1) mirrored horizontally
scaleY : image is (-1) or isn't (1) mirrored upside down
dimensionSwapped : image is rotated by 90° or 270°. Fixing rotation would swap width and height.
css : can/can't be rotated with CSS and transform: rotate() (important for ios Safari)
canvas : can/can't be rotated with canvas and ctx.rotate() (important for ios Safari)
Warning: Some modern browsers autorotate elements, background-image and/or data passed to without altering the EXIF. The behavior is extra quirky on iOs 13.4 Safari and newer (though not on macos). You may end up with over-rotated image if you don't handle this quirk. See examples/orientation.html to learn more.
`js
rotate(${r.deg}deg) scale(${r.scaleX}, ${r.scaleY})
`
$3
Promise
Uint8Array.
Only parses as little EXIF as necessary to find offset of the thumbnail.
examples/thumbnail.html and examples/thumbnail.js to learn more.
$3
Promise
Object URL . The URL has to be revoked when not needed anymore.
$3
Promise
.xmp or .icc.
file is path or url) and/or randomly tries all parsers at its disposal.
`js
`
$3
new Exifr(options) class
.read(file) to load the file
.parse() or .extractThumbnail() to get an output
Exif yourself to parse metadata and extract thumbnail efficiently at the same time. In Node.js it's also necessary to close the file with .file.close() if it's read in the chunked mode.
`js
`
$3
string
Object URL
Base64 URL
Buffer
ArrayBuffer
Uint8Array
DataView
Blob, File
element
$3
array of tags to parse, shortcut for options.pick
true shortcut to parse all segments and blocks
object with granular settings
`js
`
$3
Tip: Using numeric tag codes is even faster than string names because exifr doesn't have to look up the strings in dictionaries.
options.pick
Array
`js
`
options.skip
Array
['MakerNote', 'UserComments']
elsewhere .
`js
`
$3
options.tiff type bool|object|Array default: true
options.jfif type bool default: false
options.xmp type bool default: false
options.iptc type bool default: false
options.icc type bool default: false
options.ihdr type bool default: true (only for PNG)
options.ifd0 (alias options.image) type bool|object|Array default: true
options.ifd1 (alias options.thumbnail) type bool|object|Array default: false
options.exif type bool|object|Array default: true
options.gps type bool|object|Array default: true
options.interop type bool|object|Array default: false
options.makerNote type: bool default: false
options.userComment type: bool default: false
output. E.g. output.xmlns, output.GPano, output.crs, etc...
options.multiSegment
Exifr contains minimalistic opinionated XML parser for parsing data from XMP. It may not be 100% spec-compliant, because XMP is based on XML which cannot be translated 1:1 to JSON. The output is opinionated and may alter or simplify the data structure. If the XMP parser doesn't suit you, it can be disabled by setting options.xmp.parse to false. Then a raw XMP string will be available at output.xmp.
options.mergeOutput:false: Tags of tiff namespace () are merged into output.ifd0. Likewise exif ns is merged into output.exif.
`xml
Mike Kovařík
Some string here
jpeg xmp tiff iptc
`
`js
`
options.multiSegment
bool
false
In some rare cases the photo can contain additional layers, embedded images, or metadata that doesn't fit inside single 64kB (JPEG) segment.
options.xmp.multiSegment
options.icc.multiSegment
options.tiff serves as a shortcut for configuring all TIFF blocks:
options.tiff = true enables all TIFF blocks (sets them to true).
options.tiff = false disables all TIFF blocks (sets them to false) except for those explicitly set to true in options.
options.tiff = {...} applies the same sub-options to all TIFF blocks that are enabled.
options.tiff = false can be paired with any other block(s) to disable all other blocks except for said block.
`js
`
tiff segment can also be configured with object or array, much like the options argument.
object - enabled with custom options - filters (pick, skip) and formatters (translateKeys, translateValues, reviveValues)
array - enabled, but only picks tags from this array
options.tiff and then from options.
`js
`
$3
options.chunked
bool
true
How it works: A first small chunk (of firstChunkSize) is read to determine if the file contains any metadata at all. If so, reading subsequent chunks (of chunkSize) continues until all requested segments are found or until chunkLimit is reached.
Supported inputs: Chunked is only effective with Blob, element, string url, disk path, or base64. These inputs are not yet processed or read into memory. Each input format is implemented in a separate file reader class. Learn more about file readers and modularity here .
If you use URL as input: Fetching chunks (implemented in UrlFetcher) from web server uses HTTP Range Requests . Range request may fail if your server does not support ranges, if it's not configured properly or if the fetched file is smaller than the first chunk size. Test your web server or disable chunked reader with {chunked: false} when in doubt.
options.firstChunkSize
number
512 Bytes in Node / 65536 (64 KB) in browser
In browser, it's usually better to read just a larger chunk in hope that it contains the whole EXIF (and not just the beginning) instead of loading multiple subsequent chunks. Whereas in Node.js it's preferable to read as little data as possible and fs.read() does not cause slowdowns.
options.chunkSize
number
65536 Bytes (64 KB)
options.chunkLimit
number
5
options.
options.multiSegment allows reading all of them.
If the exif isn't found within N chunks (64\ 5 = 320KB) it probably isn't in the file and it's not worth reading anymore.*
options.httpHeaders
object
$3
options.mergeOutput
bool
true
Warning : mergeOutput: false should not be used with translateKeys: false or when parsing both ifd0 (image) and ifd1 (thumbnail). Tag keys are numeric, sometimes identical and may collide.
mergeOutput: true
mergeOutput: false
options.sanitize
bool
true
options.silentErrors
bool
true
output.errors instead of throwing and causing promise rejection.
Unknown file format.
options.translateKeys
bool
true
Model instead of 0x0110.
Model tag use output.ifd0[0x0110] or output.ifd0[272]
dictionaries .
Warning : translateKeys: false should not be used with mergeOutput: false. Keys may collide because ICC, IPTC and TIFF segments use numeric keys starting at 0.
translateKeys: false
translateKeys: true
{
{
options.translateValues
bool
true
dictionaries .
translateValues: false
translateValues: true
options.reviveValues
bool
true
dictionaries .
reviveValues: false
reviveValues: true
Advanced APIs
Modularity, Pugin API, Configure custom bundle relevant for Web Browsers , where file size and unused code elimination is important.
(Chunked) File reader reads different input data structures by chunks.
BlobReader (browser), UrlFetcher (browser), FsReader (Node.js), Base64Reader
src/file-readers/.
NOTE: Everything can read everything out-of-the-box as a whole file. But file readers are needed to enable chunked mode.
File parser looks for metadata in different file formats
.jpg, .tiff, .heic
src/file-parsers/.
Segment parser extracts data from various metadata formats (JFIF, TIFF, XMP, IPTC, ICC)
src/segment-parsers/.
Dictionary affects the way the parsed output looks.
src/dicts/.
examples/custom-build.js .
.jpg files in blob format and we want to extract ICC data in human-readable format. For that we'll need dictionaries for ICC segment.
`js
`
.heic and .tiff photos, extract EXIF block (of TIFF segment). We only need the values to be translated. Keys will be left untranslated but we don't mind accessing them with raw numeric keys - output[0xa40a] instead of output.Sharpness. Also, we're not importing any (chunked) file reader because we only work with Uint8Array data.
`js
`
Translation dictionaries, customization full build's 60 KB). So it's a good idea to make your own bundle and shave off the dicts you don't need.
Key dict translates object keys from numeric codes to string names (output.Model instead of output[0x0110])
Value dict translates vales from enum to string description (Orientation becomes 'Rotate 180' instead of 3)
Reviver further modifies the value (converts date string to an instance of Date)
exiftool.org . Specifically these:
EXIF & GPS ),
ICC ,
IPTC ,
JFIF
`js
`
`js
`
`js
`
`js
`
Usage with Webpack, Parcel, Rollup, Gatsby, etc... fs module. The import is obviously only used in Node.js and not triggered in a browser. But your bundler may, however, pick up on it and fail with something like Error: Can't resolve 'fs'.
webpackIgnore magic comment added to the library's source code import(/ webpackIgnore: true / 'fs').
node: {fs: 'empty'} and target: 'web' or target: 'webworker' to your Webpack config. Or similar settings for your bundler of choice.
core build and do not include FsReader in it.
regenerator-runtime or reconfigure babel.
Performance
$3
Use options.pick if you only need certain tags `js
`
Disable options.ifd0 if you don't need the data `js
`
Use exifr.gps() if you only need GPS exifr.gps() because it is fine-tuned to do exactly this and nothing more. Similarly there's exifr.orientation().
`js
`
Cache options object options object instead of inlining it. Exifr uses your options to create an instance of Options class under the hood and uses WeakMap to find previously created instance instead of creating q new one each time.
`js
`
$3
File reading: You don't need to read the whole file and parse through a MBs of data. Exifr takes an educated guess to only read a small chunk of the file where metadata is usually located. Each platform, file format, and data type is approached differently to ensure the best performance.
Finding metadata: Other libraries use brute force to read through all bytes until 'Exif' string is found. Whereas exifr recognizes the file structure, consisting of segments (JPEG) or nested boxes (HEIC). This allows exifr to read just a few bytes here and there, to get the offset and size of the segment/box and pointers to jump to the next.
HEIC: Simply finding the exif offset takes 0.2-0.3ms with exifr. Compare that to exif-heic-js which takes about 5-10ms on average. Exifr is up to 30x faster.
$3
pigallery2 did a few benchmarks .
`
`
benchmark/chunked-vs-whole.js
`
`
Highest quality Google Pixel photos. Tested on a mid-range dual-core i5 machine with SSD ).
fs.readFile = 0.3ms
ArrayBuffer = 3ms
Blob = 7ms
with Object URL = 3ms
the exifr playground benchmark/gps-dnd.html , drop in your photos and watch the parsed in timer.
Changelog
CHANGELOG.md.
$3
7.0.0 string URLs as file argument are now accepted in Node.js (UrlFetcher uses polyfill for fetch() in Node.js*). But only in full bundle.
Only affects obscure cases with lists and nested rdf:Description, but breaking change nonetheless.
6.3.0 AVIF support.
6.0.0 & 6.2.0 PNG support.
4.3.0 Package.json's "main" now points to UMD bundle for better compatibility.
4.1.0 Started bundling shims and polyfills with legacy builds. Suppporting IE10.
4.0.0 Added XMP Parser and XMP Extended support.
3.0.0 Major rewrite, added ICC parser, HEIC file support, IE11 back compat, reimplemented chunked reader.
F.A.Q.
Why are there different kB sizes on npm, bundlephobia, and badge in the readme? TL;DR: Because exifr comes in three bundles, each in three format variants (ESM, UMD, legacy), each in two extensions (.js and .mjs or .mjs) due to tooling. Plus source codes are included.
npm (~1MB, ~65 files): The module includes both src/ and dist/. That's source codes of all the readers, parsers and dictionaries. Multiplied by 3 bundles (full , lite , mini ). Then multiplied by 3 bundle formats (ESM , UMD , legacy for IE10) and multiplied by 2 extensions (.mjs+.js or .cjs+.js). But you won't use all of the files. They're there so you can choose what's best for your project, tooling and environment.
bundlephobia (~63/22 kB): Full build is the "main" entry point (in package.json) picked up by Node and bundlephobia. But it's meant for use in Node where size doesn't matter.
badge in readme (~9 kB): The badge points to mini bundle which contains the bare minimum needed to cover the most use-cases (get orientation, coords, exif info, etc...). This is meant for browsers where file size matters.
Contributing
like this one ) with minimal code where the bug is reproducible.
in browser by visiting /test/index.html (uses import maps, you may need to enable experimental flags in your browser*)
npm run test`
License
