Obsidian Stats logoObsidian Stats

Linux Image Rendering Fix

by evgene-kopylov
5
4
3
2
1
New Plugin
Install Code

Description

This plugin has not been manually reviewed by Obsidian staff. Fixes image rendering issues on Linux. Ensures images display correctly on Ubuntu and other Linux distributions.

Reviews

No reviews yet.

Stats

stars
downloads
0
forks
0
days
NaN
days
NaN
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
0
commits

Latest Version

Invalid date

Changelog

See all version on GitHub

README file from

Github

Linux Image Rendering Fix

Obsidian plugin that fixes image rendering issues on Linux (Ubuntu).

Problem

On Linux, especially Ubuntu and derivatives (Pop!_OS, Linux Mint, etc.), Obsidian (an Electron/Chromium app) often fails to display local images. The issue has been reported since 2022 (v1.0.0) and remains unfixed.

The root cause is twofold:

  1. Broken app:// protocol — Electron/Chromium cannot resolve paths with non-ASCII characters: emoji, diacritics, Cyrillic, CJK, etc.
  2. Missing image codecs — some Linux Electron builds lack codecs for PNG, JPEG, WebP, causing status 0 or decode failures.

Affects Snap, Flatpak, and DEB packages. AppImage is slightly more stable but not immune. ARM systems also affected.

This is an upstream Electron/Chromium bug. The Obsidian team cannot fix it directly. This plugin provides a reliable workaround.

How it works

The plugin intercepts markdown rendering (MarkdownPostProcessor), finds all <img> elements, reads the image file directly from disk via vault.adapter.readBinary() and replaces src with a Blob URL (blob:...). This bypasses the broken app:// protocol.

Features

  • Loads images bypassing the app:// protocol
  • Supports png, jpg, gif, webp, svg, bmp
  • Automatic processing when opening a page
  • Reprocess images command for manual refresh

Installation

Symlink (recommended for development)

ln -s "$PWD" /home/death/Documents/TEST-VAULT-3/.obsidian/plugins/linux-image-rendering-fix

After npm run build, Obsidian picks up the new main.js on plugin reload.

Copy files

Copy main.js, manifest.json, styles.css to the plugin directory:

<Vault>/.obsidian/plugins/linux-image-rendering-fix/

Issues

Bug reports and feature requests: https://github.com/Evgene-Kopylov/linux-image-rendering-fix/issues

Development

Development happens on GitLab: https://gitlab.com/Evgene-Kopylov/linux-image-rendering-fix

npm install
npm run dev    # watch mode
npm run build  # production build
npm run lint   # ESLint
npm run test   # Vitest

License

LGPL-3.0

Sponsors