# term-img

> Display images in terminals using the iTerm inline image protocol

Latest version **7.1.0** (published 2025-10-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install term-img
pnpm add term-img
yarn add term-img
bun add term-img
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.1.0 |
| Published | 2025-10-07 |
| First published | 2016-03-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 7.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 318 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | term, image, iterm, iterm2, terminal, shell, console, command-line, img, pic, picture, photo, app, version, ansi, escape, gif, gifs, jpg, jpeg |

## Links

- npm: https://www.npmjs.com/package/term-img
- Repository: https://github.com/sindresorhus/term-img
- Homepage: https://github.com/sindresorhus/term-img#readme
- Issues: https://github.com/sindresorhus/term-img/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/term-img

## Dependencies (2)

- [ansi-escapes](https://npm.io/package/ansi-escapes.md) ^7.1.1
- [iterm2-version](https://npm.io/package/iterm2-version.md) ^5.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 7.1.0 (latest) — 2025-10-07
- 7.0.0 — 2024-07-26
- 6.0.0 — 2021-05-03
- 5.0.0 — 2020-05-21
- 4.1.0 — 2019-04-05
- 4.0.0 — 2018-12-12
- 3.0.0 — 2018-11-30
- 2.1.0 — 2017-07-23
- 2.0.0 — 2017-07-23
- 1.0.0 — 2017-01-13
- 0.2.0 — 2016-03-17
- 0.1.2 — 2016-03-09
- 0.1.1 — 2016-03-09
- 0.1.0 — 2016-03-09

## README

# term-img

> Display images in terminals using the iTerm inline image protocol

You probably want the higher-level [`terminal-image`](https://github.com/sindresorhus/terminal-image) package for displaying your images.

![](screenshot.jpg)

Even [animated gifs](https://github.com/vdemedes/gifi)!

*Currently only supported on [iTerm >=3](https://www.iterm2.com/downloads.html), [WezTerm](https://wezfurlong.org/wezterm/), [Konsole](https://konsole.kde.org/), [Rio](https://rioterm.com/), and [VSCode integrated terminal](https://code.visualstudio.com/).*

## Install

```sh
npm install term-img
```

## Usage

```js
import terminalImage from 'term-img';

function fallback() {
	// Return something else when not supported
}

console.log(terminalImage('unicorn.jpg', {fallback}));
```

## API

### terminalImage(image, options?)

Get the image as a `string` that you can log manually.

#### image

Type: `string | Uint8Array`

File path to an image or an image as a buffer.

#### options

Type: `object`

##### width
##### height

Type: `'auto' | string | number`

The width and height are given as a number followed by a unit, or the word `'auto'`.

- `N`: N character cells.
- `Npx`: N pixels.
- `N%`: N percent of the session's width or height.
- `auto`: The image's inherent size will be used to determine an appropriate dimension.

##### preserveAspectRatio

Type: `boolean`\
Default: `true`

##### fallback

Type: `Function`\
Default: `() => throw new UnsupportedTerminalError()`

Enables you to do something else when the terminal doesn't support images.

## Related

- [term-img-cli](https://github.com/sindresorhus/term-img-cli) - CLI for this module
- [term-kitty-img](https://github.com/tbjgolden/term-kitty-img) - Similar package but for Kitty, Konsole, WezTerm

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