Post

View and paste images in neovim

If you use neovim as your main markdown editor and want to view and paste images, the same way you do in obsidian

Posted Updated
Preview Image
By Christian Arzu
12 min read

Contents

YouTube video

If you like this, and want to support me

Follow me on Twitter

Objectives

  • See images in neovim, the same way you look at them in note taking apps like Obsidian.md
    • If you want to see videos on how I configured Obsidian, let me know in the comments
  • Paste images in neovim, also the same way you do in Obsidian

Quick demo (overview)

  • In the video I’ll show you how this works so you can see if this is for you or not

Important info

Requirements

  • macOS (Linux also works)
    • This tutorial is for macOS, but Linux users should be able to follow along or at least have a starting point
    • Linux users: go to the repos below to see what other dependencies need to be installed for your distribution

Star the repos if you like the plugins

This guide will be on my blog

  • You don’t have to type all of these commands, this file will be uploaded to my blogpost linkarzu.com when I’m done with the video, so you can follow along and just paste the commands

Like and comment

  • If you like my videos and you want me to keep making more, once you’ve finished watching it, please give it a like and comment
  • This helps me a lot so that YouTube shows the video to more people

My complete Neovim markdown setup and workflow in 2024

  • If you like this current article, you will find this quite useful:

image.nvim

  • This is the plugin that allows you to view images in neovim

Install image.nvim dependencies

Homebrew

kitty terminal

  • kitty terminal (see installation and setup instructions below)
    • There’s an alternative, so that you don’t use kitty, which involves using ueberzugpp. I ain’t doing that
  • I had been using the Alacritty terminal emulator for quite some time, it worked wonderfully. I had no plans of switching, until I decided I wanted to see images in my terminal the same way I do in Obsidian, so to make my life easier, I decided to switch to kitty
    • As of today Jun 2024, as far as I’m aware, it’s not possible to view images in Alacritty
    • So even if you’re not a cat person, you’ll have to switch to kitty :wink:
    • I don’t know if WezTerm is compatible with the dependencies needed, nor I want to find out
  • I’m loving kitty so far, people say it’s faster than Alacritty, or I don’t remember if it’s the other way around. I can’t tell, both of the terminal emulators work well for me and I don’t feel a difference. Maybe I just haven’t used kitty long enough
  • I do not like all the built-in stuff that kitty has, like tabs, layouts, and I haven’t even looked at what other things it offers
    • I want my terminal to be just that, a terminal emulator, I don’t want dependencies to a specific terminal in case I decide to switch to another one in the future. So I just use kitty as a basic terminal emulator, I don’t use any of the features it has built-in
    • I use tmux to manage my sessions, windows and panes, if you want to learn more you can watch my tmux video
  • Once you have brew installed, let’s install kitty
1
2
3
4
5
6
7
8
9
10
11
12

# This installs the kitty terminal
brew install --cask kitty

# Im also installing the fonts I like to use currently with my kitty config
brew install --cask font-meslo-lg-nerd-font

# This also downloads the kitty themes and puts them in the directory where my
# config looks
mkdir -p ~/github/dotfiles-latest/kitty/themes/
git clone --depth 1 https://github.com/kovidgoyal/kitty-themes.git ~/github/dotfiles-latest/kitty/themes/
rm -rf ~/github/dotfiles-latest/kitty/themes/.git/
rm -rf ~/github/dotfiles-latest/kitty/themes/.github/
  • If you want to use my kitty settings, you can find my config file in my dotfiles
    • My kitty config file
    • Just copy the settings in my config file to your ~/.config/kitty/kitty.conf file
  • If you don’t know what dotfiles are or how to clone them, you can watch my dotfiles video
    • I’ve put a lot of work in my dotfiles-latest repo so if you find it useful, and have the time, please star it
  • Since you want to see images in neovim, open kitty and continue there

ImageMagick

  • ImageMagick
  • ImageMagick is an open source set of tools used to create, edit, compose, or convert bitmap images
  • Since we’ll be working with images, we need to install it with brew
1

brew install imagemagick
  • To confirm that ImageMagick is installed
1

identify -version

1
2
3
4
5
6
7
8
9
10

linkarzu.@.mini~/github
[24/06/02 13:38:40]
❯ identify -version

Version: ImageMagick 7.1.1-32 Q16-HDRI aarch64 22207 https://imagemagick.org
Copyright: (C) 1999 ImageMagick Studio LLC
License: https://imagemagick.org/script/license.php
Features: Cipher DPC HDRI Modules OpenMP(5.0)
Delegates (built-in): bzlib fontconfig freetype gslib heic jng jp2 jpeg jxl lcms lqr ltdl lzma openexr png ps raw tiff webp xml zlib zstd
Compiler: gcc (4.2)
  • >>>>>>>>>> REALLY IMPORTANT <<<<<<<<<<
  • Review the imagemagick package information, pay close attention to the Dependencies section
    • Notice that I’m not missing the pkg-config one
    • Otherwise you would see an x next to the name
  • Images were not working for me, and figuring out it was related to one of these dependencies took me a day, so pay close attention to this part
  • If you have any missing dependencies, install them using brew (see example below)
1

brew info imagemagick

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

linkarzu.@.mini~/github
[24/06/02 13:38:42]
❯ brew info imagemagick

==> imagemagick: stable 7.1.1-33 (bottled), HEAD
Tools and libraries to manipulate images in many formats
https://imagemagick.org/index.php
Installed
/opt/homebrew/Cellar/imagemagick/7.1.1-32 (809 files, 32.3MB) *
  Poured from bottle using the formulae.brew.sh API on 2024-05-22 at 16:22:20
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/i/imagemagick.rb
License: ImageMagick
==> Dependencies
Build: pkg-config ✔
Required: fontconfig ✔, freetype ✔, ghostscript ✔, jpeg-turbo ✔, jpeg-xl ✔, libheif ✔, liblqr ✔, libpng ✔, libraw ✔, libtiff ✔, libtool ✔, little-cms2 ✔, openexr ✔, openjpeg ✔, webp ✔, xz ✔, gettext ✔, glib ✔, imath ✔, libomp ✔
==> Options
--HEAD
        Install HEAD version
==> Analytics
install: 76,865 (30 days), 217,784 (90 days), 894,695 (365 days)
install-on-request: 70,276 (30 days), 201,905 (90 days), 824,794 (365 days)
build-error: 19 (30 days)
  • Just as an example, let’s say you’re missing the pkg-config dependency, install it through brew with
1

brew install pkg-config

Lua

  • You need to have lua installed
  • Notice I have version 5.4.6 installed
1

lua -v

1
2
3
4

linkarzu.@.mini~/github
[24/06/03 04:42:17]
❯ lua -v
Lua 5.4.6  Copyright (C) 1994-2023 Lua.org, PUC-Rio
  • If you don’t have it installed, install it with
1

brew install lua

Curl

  • This is optional and used to view remote images (images in URLs)
  • It already comes installed with macOS by default, so you don’t need to install it
1

curl --version

1
2
3
4
5
6
7

linkarzu.@.mini~/github
[24/06/03 04:52:49]
❯ curl --version
curl 8.4.0 (x86_64-apple-darwin23.0) libcurl/8.4.0 (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.58.0
Release-Date: 2023-10-11
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL threadsafe UnixSockets

Configure TMUX

  • If you’re a tmux user, add this to your tmux configuration file
1
2
3
4
5
6

# https://github.com/3rd/image.nvim/?tab=readme-ov-file#tmux
# This is needed by the image.nvim plugin
set -gq allow-passthrough on
# This is related to the `tmux_show_only_in_active_window = true,` config in
# image.nvim
set -g visual-activity off
  • Then make sure to reload the tmux config
  • I reload my tmux config with ctrl+b r from any window inside tmux
  • That’s the keymap I configured it
  • If you want to learn how to configure tmux and what it’s used for, watch my tmux video

TMUX caveat

  • I navigate through different directories/repos using tmux sessions
  • When you’re looking at a file that has images open, and switch to another tmux session, the images will be shown on the other tmux session, this is a known behavior, if you want to find out more, you can join the image.nvim discord that can be found in the github repo
  • I already asked about this, so don’t post a new question, just search tmux-session-A and you’ll get to the right place
  • I just switch to a part of the file that doesn’t show images before I switch to another tmux session
  • I set a neovim keymap <leader>ic to clear all images in the current buffer
    • From within neovim you can clear the images with the :lua require("image").clear() command
    • If outside neovim you could try nvim -c 'lua require("image").clear()' -c 'qa!'
      • This opens neovim, clears images and then quits
  • You could also change the plugin behavior to only_render_image_at_cursor to avoid this
  • Its up to how you want to manage it

Install image.nvim

  • Remember that this is the plugin that will allow us to view images in neovim and configure their settings, like size, if all of the images are shown or only the one under the cursor, show remote images (images from URLs), etc.
  • I’m using the lazyvim.org distro
  • The config I’m using for this plugin can be found in my dotfiles
  • Install this like any other neovim plugin
  • So just create the plugin file for image.nvim, which in my case is the file shown above
    • This will install luarocks via luarocks.nvim, and the magick dependency needed to view images
    • If you do this, you don’t need to install luarocks locally
    • luarocks.nvim allows you to install luarocks packages directly within Neovim. It simplifies the process of managing Lua dependencies
      • https://github.com/vhyrro/luarocks.nvim
  • We’ll cover the plugin settings later in the video

Troubleshooting: Re-install luarocks.nvim

  • Only do this if for a strange reason, after installing all the dependencies and packages mentioned above you still get errors when opening neovim
  • Remember I’m using the lazyvim.org distro
  • So to reinstall luarocks:
    • :Lazy to open lazy.nvim
    • Search for luarocks in the main window and press x to uninstall it
    • Then quit neovim
    • It will be re-installed when you re-open neovim

Configure image.nvim

  • In the video I go over the plugin config

img-clip.nvim

  • This plugin is used if you want to be able to paste images in neovim.
  • I have it configured to paste the images in a subdir where the file is, and convert all those images to the webp format with a quality of 75

Install img-clip.nvim dependencies

ImageMagick (already installed)

  • We already installed this above
  • I use ImageMagick to convert an compress the images to save space
  • It gets invoked when you use the process_cmd command in the config file
    • We will see examples in the video

pngpaste

  • Paste PNG into files on MacOS
  • I understand that this is used to capture images from the system clipboard and save them as files
  • This is listed as an optional dependency in the repo, but I installed it anyway
1

brew install pngpaste

Install img-clip.nvim

  • Install this plugin like any other neovim plugin
  • The config I’m using for this plugin can be found in my dotfiles

Configure img-clip.nvim

  • In the video in which I go over the plugin config

Tips and tricks

  • The following tips and their respective code will be covered in the video as I open a test file and view images, and paste images in different formats
  • I configured the following neovim keymaps, if using Linux, make sure to update them so they work
    • <leader>io (macOS)
      • open the image in the preview app
    • <leader>if (macOS)
      • show the current image in Finder
    • <leader>id (macOS)
      • Delete the image file under the cursor using the trash app
      • Needs the trash app installed
      • brew install trash
    • <leader>ir
      • Refresh images in the current buffer without re-opening neovim
    • <leader>ic
      • Clear all the images in current buffer
    • <leader>mp
      • View the file in the web browser iamcco/markdown-preview.nvim
      • This comes by default with the lazyvim.org distro using <leader>cp
  • All of these keymaps and my plugin configs can be found in my dotfiles-latest repo

Petition (reminder)

  • If you like my videos and you want me to keep making more, once you’ve finished watching it, please give it a like and comment
  • This helps me a lot so that YouTube shows the video to more people
neovim
macos tutorial youtube video neovim
This post is licensed under CC BY 4.0 by the author.