universal-clipboard.nvim

A minimal Neovim plugin that automatically sets up sharing your system clipboard across multiple platforms. It addresses this issue:

Platform Differences: On macOS, Neovim appears to behave nicely with the system clipboard. On others, not so much. External tools can help. For example, there’s wl-copy/wl-paste for Wayland or xclip/xsel for X11.

With universal-clipboard.nvim:

• If we detect an external clipboard tool (wl-clipboard, xclip, xsel), we configure Neovim’s clipboard to use it.
• Otherwise, we simply set clipboard to unnamedplus with no further configuration needed.

Installation

Using packer.nvim:

use({
  "swaits/universal-clipboard.nvim",
  config = function()
    require("universal-clipboard").setup({
      verbose = false, -- optional: set true to log detection details
    })
  end,
})

Or lazy.nvim:

{
  "swaits/universal-clipboard.nvim",
  opts = {
    verbose = true, -- optional: set true to log detection details
  },
}

Note

: If your Neovim lacks +clipboard, make sure you have at least one of wl-clipboard, xclip, or xsel installed. Or you may customize the tools searched -- see below.

---

Default Options

{
  -- If true, prints the chosen clipboard mode/tool at startup
  verbose = false,

  -- A table of tools to check, in order
  tools = {
    {
      name = "wl-clipboard",
      -- Either a string (the executable name) or a function returning boolean
      detect = function()
        local wayland_display = os.getenv("WAYLAND_DISPLAY")
        local wayland_runtime = os.getenv("XDG_RUNTIME_DIR")
        local socket_path = (wayland_runtime or "") .. "/" .. (wayland_display or "")
        return (vim.fn.executable("wl-copy") == 1)
          and (vim.fn.executable("wl-paste") == 1)
          and wayland_display ~= ""
          and (vim.fn.isdirectory(socket_path) == 1)
      end,
      commands = {
        copy = "wl-copy",
        paste = "wl-paste --no-newline",
      },
    },
    {
      name = "xclip",
      detect = "xclip", -- Will check vim.fn.executable("xclip")
      commands = {
        copy = "xclip -selection clipboard",
        paste = "xclip -selection clipboard -o",
      },
    },
    {
      name = "xsel",
      detect = "xsel",
      commands = {
        copy = "xsel --clipboard --input",
        paste = "xsel --clipboard --output",
      },
    },
  },
}

Customizing Tools

If you want to add or remove tools, you can override the tools table in your setup() call. For example:

require("universal-clipboard").setup({
  verbose = true,
  tools = {
    -- If you only want xclip, for instance:
    {
      name = "xclip-only",
      detect = "xclip",
      commands = {
        copy = "xclip -selection clipboard",
        paste = "xclip -selection clipboard -o",
      },
    },
    -- Or add more custom entries
  },
})

The plugin will iterate over tools in order and select the first one that is “available.”

---

Usage

Once installed, no additional steps are required. The plugin configures your clipboard on startup. Simply copy and paste in Neovim as usual.

Commands

• :UniversalClipboardCheck Prints the current clipboard configuration to the command line, showing what vim.opt.clipboard and vim.g.clipboard are set to.

• :UniversalClipboardReinit Re-runs the detection logic, forcing verbose mode for that run to help troubleshoot. You normally do not need this, but it can be helpful if you install a new system tool after starting Neovim and want to see if it’s detected.

---

License

MIT License