explaingit

shenawy29/xdg-nvfilechooser.nvim

Analysis updated 2026-05-18

19LuaAudience · developerComplexity · 3/5Setup · hard

TLDR

A Neovim plugin that replaces your Linux desktop's file-upload picker with a fast, keyboard-driven fuzzy finder inside Neovim.

Mindmap

mindmap
  root((xdg-nvfilechooser))
    What it does
      Replaces GUI file picker
      Fuzzy find in Neovim
      XDG portal backend
    Tech stack
      Lua
      Neovim
      snacks.picker
    Use cases
      Browser upload dialogs
      Fast file navigation
      Linux desktop portals
    Audience
      Linux terminal users
      Neovim power users
    Setup
      Needs fd tool
      Nix or manual install
      Systemd service

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Replace the slow mouse-driven GTK or Gnome file picker with a Neovim fuzzy finder.

USE CASE 2

Pick files for browser uploads using the same fuzzy search you use to navigate code.

USE CASE 3

Set up an XDG portal backend on a Linux desktop like Hyprland or Sway.

USE CASE 4

See a real example of building a custom XDG file-chooser portal for Linux.

What is it built with?

LuaNeovim

How does it compare?

shenawy29/xdg-nvfilechooser.nvimbjarneo/omarchy-ochre-themefullband7/openwrt-theme-foxhound
Stars191616
LanguageLuaLuaLua
Setup difficultyhardeasymoderate
Complexity3/51/53/5
Audiencedevelopergeneralops devops

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1h+

Requires installing a separate backend binary plus registering XDG portal, D-Bus, and systemd files on Linux.

In plain English

This is a Linux plugin for the Neovim text editor that solves a specific annoyance: when a website shows a file-upload button, your operating system normally opens a graphical file browser (like the GTK or Gnome file picker) to let you choose a file. If you live in the terminal and use Neovim with keyboard-driven fuzzy searching to navigate files, switching to a slow mouse-based file browser feels jarring. This project replaces that system-level file picker with a fuzzy file finder running inside Neovim. When any application triggers a file-upload dialog, instead of the standard GUI browser popping up, a Neovim window opens in your terminal with a fuzzy search interface powered by the snacks.picker plugin. You start typing part of the filename, results filter instantly, and you select with the keyboard. Under the hood, it works by registering itself as an XDG portal backend, a standard Linux mechanism that lets desktop applications delegate file-picking to a third party. It also relies on fd (a fast alternative to the system find command) to list files breadth-first so shallower, more likely candidates appear first. You would use this if you work primarily in a Linux terminal environment with Neovim and find yourself repeatedly interrupted by the system GUI file picker whenever you upload a file in a browser or application. The plugin is written in Lua and the backend binary is a separate companion project. Installation instructions are provided for both Nix-based systems and standard Linux setups.

Copy-paste prompts

Prompt 1
Walk me through installing xdg-nvfilechooser.nvim as an XDG portal backend on my Linux system.
Prompt 2
Explain how the fd tool and snacks.picker work together in this plugin.
Prompt 3
Show me the Nix flake configuration needed to register this as my file chooser portal.
Prompt 4
How do I set the XDG_NVFILECHOOSER_TERMINAL environment variable and why is it needed?

Frequently asked questions

What is xdg-nvfilechooser.nvim?

A Neovim plugin that replaces your Linux desktop's file-upload picker with a fast, keyboard-driven fuzzy finder inside Neovim.

What language is xdg-nvfilechooser.nvim written in?

Mainly Lua. The stack also includes Lua, Neovim.

How hard is xdg-nvfilechooser.nvim to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is xdg-nvfilechooser.nvim for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.