Pixel Diff for VS Code

Compare two images side-by-side with synced zooming and panning, pixel-level diff highlighting, and a slider wipe mode. Supports all image formats shown by the VS Code built-in image viewer: PNG, JPEG, BMP, GIF, ICO, WebP, and AVIF.

Features

Opening the Diff Viewer

There are four ways to open Pixel Diff, depending on where you are:

Command Palette

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run Pixel Diff: Compare Two Images.... You'll be prompted to pick two image files from your filesystem.

Explorer context menu

Right-click any supported image file in the Explorer panel:

• Pixel Diff: Compare with... — pick a second file to compare against
• Pixel Diff: Compare with Git HEAD — diff the file against its last committed version (requires an open Git repository)

Editor title bar

Open an image file in VS Code. Two diff icons appear in the editor title bar:

• The $(diff) icon opens a file picker so you can compare it with any other file
• The $(git-compare) icon diffs it against Git HEAD

SCM panel

New: Pixel Diff replaces the default (broken) diff editor automatically when you click an image in the Source Control panel.

By default, clicking any image in the Source Control panel opens Pixel Diff instead of VS Code's built-in diff editor, which cannot display binary image files properly. The HEAD version is shown on the left and the working copy on the right.

• Newly-added images — no HEAD version exists, so the left side shows a blank placeholder.
• Deleted images — no working copy exists, so the right side shows a blank placeholder.

To disable automatic interception and fall back to the default behaviour, set imageDiff.interceptScmImageDiff to false in your settings.

You can also right-click any changed image and choose Pixel Diff: Compare with Git HEAD directly from the context menu.

Layout Modes

Switch between layouts using the dropdown in the top-left of the toolbar. Your choice applies immediately — no need to reload.

Side by Side

Both images are displayed next to each other with a divider between them. When the panel is too narrow to fit both, they stack automatically.

Stacked

Both images are shown one above the other. Useful when comparing tall images or when you want a full-width view of each.

Overlay (Diff)

Image A is shown with diff pixels drawn on top according to the active diff mode (binary or heatmap). The checkerboard pattern in transparent areas indicates pixels that were removed or are fully transparent.

See Diff Modes below for how the overlay is rendered.

Slider Wipe

A draggable handle divides the canvas: image A is shown on the left and image B on the right. Drag the handle to slide the reveal point. The label at the top of each side identifies which image is which.

Diff Modes

Diff modes only apply when the layout is Overlay (Diff). Switch between them using the second dropdown in the toolbar.

Binary

Each pixel in image B that differs from image A by more than the sensitivity threshold is painted in the chosen highlight color (default: red). Pixels within the threshold are left unchanged.

• Use the Color swatch to pick any highlight color.
• Use the Sensitivity slider (0–255) to control how much difference counts. A value of 0 marks every non-identical pixel; 255 only marks extreme changes.

Heatmap

Each changed pixel is colored on a spectrum from blue (small difference) through green and yellow to red (large difference). Opacity is proportional to the magnitude of the change, so subtle differences are semi-transparent and large differences are fully opaque.

No color picker or sensitivity slider is shown in heatmap mode — the coloring is computed automatically.

No differences detected — when the images are identical, the overlay canvas is fully transparent and you'll see only the checkerboard:

Zoom & Pan

All layouts support synchronized zoom and pan:

• Zoom — scroll the mouse wheel (or pinch on a trackpad) over either image
• Pan — click and drag on either image
• Reset zoom — click the Reset zoom button in the toolbar to return to the default fit

Both images always stay in sync: zooming or panning one side moves the other by the same amount.

Supported Image Formats

PNG, JPEG/JPG, BMP, GIF, ICO, WebP, AVIF

Settings

Development

Prerequisites

• Node.js 18+
• VS Code 1.85+

Setup

git clone https://gitlab.com/johnwebbcole/image-diff-for-vscode.git
cd image-diff-for-vscode
npm install
node scripts/generate-fixtures.js   # generates test PNGs and icon.png
npm run compile

Run the extension locally

Press F5 in VS Code to open a new Extension Development Host window with the extension loaded.

Testing

The project has two test suites. Run both when validating changes.

Unit & integration tests (Mocha + vscode-test)

These tests run inside a real VS Code instance via @vscode/test-electron. VS Code Stable must be closed first, or the runner will download VS Code Insiders automatically.

npm test

Test files live in src/test/suite/*.test.ts and use the tdd Mocha UI (suite / test). The workspace fixture folder is src/test/fixtures/.

Visual regression tests (Playwright)

Playwright tests open the webview HTML in headless Chromium and compare screenshots against committed baselines.

npm run test:playwright

After intentional UI changes, update the baseline snapshots:

npx playwright test --update-snapshots

Test specs live in playwright/*.spec.ts. Baselines are stored in playwright/*.spec.ts-snapshots/.

Testing during development

1. Run npm run watch to recompile on every save.
2. Press F5 to launch an Extension Development Host with the extension loaded.
3. After making changes, press Cmd+R (macOS) / Ctrl+R (Windows/Linux) in the dev host to reload and pick up the new build.

Package for local install

npx vsce package
code --install-extension image-diff-for-vscode-0.0.1.vsix

Architecture

src/
  extension.ts        — activate(), registers 4 commands
  imageDiffPanel.ts   — WebviewPanel lifecycle, image loading, messaging
  gitUtils.ts         — vscode.git API: read HEAD version of an image file
  diffAlgorithm.ts    — Pure TypeScript pixel-diff functions (used by tests)
media/
  webview.css         — Layout, toolbar, slider styles
  webview.js          — All webview UI: zoom/pan, diff computation, layout switching

License

MIT — see LICENSE.

Author

John Cole — jwc.dev · Bluesky · LinkedIn