Common Issues

July 31, 2026 · View on GitHub

English | 中文

How it works

This extension works by editting the vscode's html file.

How to get local images' address

Local images can be dragged into the browser to quickly get the file protocol address from the address bar.

Local paths also support ~ (home directory) and environment variables (${HOME} or $HOME), e.g. ~/Pictures/img.png, ${HOME}/Pictures/img.png.

Warn Your Code installation appears to be corrupt

Starting from v2.0, this issue should not occur again. Regardless, you can refer to How to uninstall section.

Disable/Uninstall doesn't remove background images

Refer to How to uninstall section.

How to uninstall

three ways:

  1. Recommended way:

    • Click the 「Background」 button on the right-bottom of statusbar, choose Uninstall the extension, automatically complete uninstall.

  2. Disable and then uninstall:

    • Set the config {"background.enabled": false} in settings.json
    • Then uninstall the extension.

  3. Not recommended:

    • If you uninstall this extension directly, don't worry.
    • Exit vscode completely, then open vscode.
    • Reload again, now it's clean.
    • ... It's a strange limit of vscode.

read-only file system

vscode needs to be located in a location with write permission.

  • windows:
    • Right click on vscode icon, choose Run as administrator.
  • mac:
    • Move Visual Studio Code.app from Download to the Application directory.
    • Run sudo chmod -R a+rw '/Applications/Visual Studio Code.app' to grant write permissions.
  • linux:
    • Run sudo chmod -R a+rw /usr/share/code
    • Some Arch Linux: sudo chmod -R a+rw /opt/visual-studio-code
    • Code Server (docker): sudo chmod -R a+rw '/usr/lib/code-server'
      • code-server needs to force browser refresh (avoid caching) for configuration to take effect.

Unsupported environment

  • Installed by snap is not supported. #382
    • Error: (Linux) snap: read-only file system
    • Snap use SquashFS to storage packages, which is a compressed readonly file system.
  • vscodium is not fully supported.
    • It works fine in most cases. But I don't use it that much, pr welcome.

VSCode crashes #306

Whenever there is an extreme situation where vscode crashes, you can manually fix it as follows:

  1. Open the directory:
    • windows: %LocalAppData%\Programs\Microsoft VS Code\resources\app\out\vs\workbench
    • mac: /Applications/Visual Studio Code.app/Contents/Resources/app/out/vs/workbench
    • linux: /usr/share/code/resources/app/out/vs/workbench
      • Some Arch Linux: /opt/visual-studio-code/resources/app/out/vs/workbench
  2. Edit workbench.html, remove from <!-- vscode-background-start to <!-- vscode-background-end -->.

Prefer v1 default images?

You can download the default images of v1 version from here, or use the config below:

{
  "background.editor": {
    "images": [
      "https://user-images.githubusercontent.com/9987486/40583669-d6189844-61c5-11e8-89e3-c52ad153da09.png",
      "https://user-images.githubusercontent.com/9987486/40583670-d6478c9e-61c5-11e8-9551-6b55eacc7b8d.png",
      "https://user-images.githubusercontent.com/9987486/40583671-d676c6e4-61c5-11e8-94cb-34ec4a12fa01.png"
    ]
  }
}