Neovim Platforms

Up: Neovim Config Tutorial Down: LSP, LSP plugins, debug test data plugins

This config is portable, but it is not platform-blind. It treats NixOS and non-Nix Linux differently because they solve package management differently.

The Rule

On NixOS, do not use Mason to install LSPs, formatters, linters, or debuggers.

Use a project devShell, devenv, flake shell, or system package instead.

On other Linux systems, Mason can be a convenience fallback, but even there the cleaner long-term pattern is to put tools near the project.

Why Mason Is Disabled On NixOS

Mason downloads prebuilt tools into Neovim’s data directory. That is convenient, but it is not declarative. NixOS wants the toolchain to be described by Nix and made available on $PATH.

The config encodes that split:

enabled = O.lsp and not O.is_nixos

That condition appears around Mason LSP and Mason DAP support. When O.is_nixos is true, Mason stays out of the way.

devenv Pattern

The config repository itself uses devenv through .envrc:

eval "$(devenv direnvrc)"
use devenv

The project environment then provides the tools Neovim expects:

{ pkgs, ... }:
 
{
  packages = with pkgs; [
    nixd
    nil
    lua-language-server
    stylua
  ];
}

When direnv.vim enters the project, the editor breathes that environment. The LSP client starts nixd or lua-language-server from $PATH. Formatting finds stylua. No hidden editor-local package manager is needed.

shell.nix Pattern

A simple shell.nix can do the same job:

{ pkgs ? import <nixpkgs> {} }:
 
pkgs.mkShell {
  packages = with pkgs; [
    lua-language-server
    stylua
    selene
  ];
}

This is useful for small repositories, shared examples, or machines that do not use flakes yet.

Non-Nix Linux

On a regular Linux system, the same Neovim config can run with system packages, language package managers, or Mason. Mason is not evil. It is just the wrong owner on NixOS.

Think of it like this:

Platform	Tool owner
NixOS	devShell, devenv, flake, or system configuration
Other Linux	Project packages, distro packages, or Mason as fallback
Remote/headless	Whatever the remote shell exposes on $PATH

Related: Nix dev shells, editor plugins