# nixos-vscode-server works around the hardcoded paths in VS Code's bundled Node > nixos-vscode-server is an experimental NixOS module that makes VS Code Server usable on NixOS by replacing the Node.js it ships with a symlink to a Nix package that works, then patching the ELF binaries. It offers a NixOS module, a flake and a Home Manager module, and it is explicit about its own limits. **nix-community/nixos-vscode-server** — Visual Studio Code Server support in NixOS - Repository: https://github.com/nix-community/nixos-vscode-server - Stars: 560 · Forks: 91 - Language: Nix - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/nix-community-nixos-vscode-server ## One problem: the bundled Node has hardcoded paths The README is short and blunt about what this project is. It offers experimental support for VS Code Server in NixOS, and it explains the reason in one sentence: the NodeJS by default supplied by VS Code cannot be used within NixOS due to missing hardcoded paths, so it is automatically replaced by a symlink to a compatible version of NodeJS that does work under NixOS. That is the whole problem statement, and it is a good one. NixOS does not have /usr/lib, and a Node build that expects to find its own libraries at a path baked in at build time will not run on a Nix store path. VS Code Server downloads its own Node to run the extension host, and that Node is built for conventional Linux layouts. So the fix is a substitution. Replace the Node VS Code Server installed with a symlink to a Node from the Nix store, and then patch the rest. The primary language of the repository is Nix, the licence is MIT, and the repository layout is small and legible. There is a flake.nix with a flake.lock, a default.nix, a modules/ directory and a pkgs/ directory. That is a package, a module set and a flake input, and nothing else. There are no GitHub releases, so the flake or the tarball is how you consume it. ## Three ways to add the module, and the enablement step that is separate The Installation section offers the module as a tarball, as a flake, and through Home Manager, and each is a small Nix expression. As a tarball in your NixOS configuration. ```nix { imports = [ (fetchTarball "https://github.com/nix-community/nixos-vscode-server/tarball/master") ]; services.vscode-server.enable = true; } ``` Or as a flake, where the module comes from the flake input and the option is set in a module of your own. ```nix { inputs.vscode-server.url = "github:nix-community/nixos-vscode-server"; outputs = { self, nixpkgs, vscode-server }: { nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem { modules = [ vscode-server.nixosModules.default ({ config, pkgs, ... }: { services.vscode-server.enable = true; }) ]; }; }; } ``` The Home Manager route is the same idea in your home configuration, in ~/.config/nixpkgs/home.nix. ```nix { imports = [ "${fetchTarball "https://github.com/msteen/nixos-vscode-server/tarball/master"}/modules/vscode-server/home.nix" ]; services.vscode-server.enable = true; } ``` The README says you can add the module in various ways, and that after the installation you will have to manually enable the service for each user. That last point is the one people miss, because the option is named enable and it does not enable the systemd unit for you. ```bash systemctl --user enable auto-fix-vscode-server.service ``` The unit is called auto-fix-vscode-server.service, and the name tells you what the service actually does. ## The warning message you are supposed to ignore Running that command prints a message that looks alarming and is entirely expected, and the README reproduces it in full. ``` The unit files have no installation config (WantedBy=, RequiredBy=, Also=, Alias= settings in the [Install] section, and DefaultInstance= for template units). This means they are not meant to be enabled using systemctl. ``` The listed possible reasons include a unit being statically enabled by being symlinked from another unit's .wants/ or .requires/ directory, a unit whose purpose is to act as a helper for some other unit with a requirement dependency on it, a unit that may be started when needed via activation such as socket, path, timer, D-Bus, udev, or a scripted systemctl call, and a template unit meant to be enabled with some instance name specified. The README is clear: however you can safely ignore it. The service will start automatically after reboot once enabled, or you can start it immediately yourself. ```bash systemctl --user start auto-fix-vscode-server.service ``` There is one real problem nearby, and it is not the warning. Enabling the user service creates a symlink to the Nix store, and the linked store path could be garbage collected at some point. The README gives a workaround for that particular issue, creating a symlink to the current system generation instead. ```bash ln -sfT /run/current-system/etc/systemd/user/auto-fix-vscode-server.service ~/.config/systemd/user/auto-fix-vscode-server.service ``` That is a Nix specific trap: an absolute reference to a store path is not a reference, it is a guess about a future. ## The FHS option, and why it is off by default The most interesting option is enableFHS, and the README explains both what it does and why it is not the default. A FHS compatible environment can be enabled to make binaries supplied by extensions work in NixOS without having to patch them. ```nix { services.vscode-server.enableFHS = true; } ``` The reason it is off by default is stated plainly. It comes with downsides, such as problematic support for SUID wrappers and terminals potentially behaving differently from a normal SSH connection. That is the right trade-off and the reason to read the option rather than just flip it. Extensions that ship prebuilt binaries expect a conventional Linux filesystem, and the FHS environment is how you give them one, at the cost of a sandbox that is not quite the same as a real login session. If your team has extensions with native binaries that fail to start, this is the switch, and you should expect the terminal difference to show up in scripts that assume a normal environment. There is a companion option for the same problem. extraRuntimeDependencies lets you add packages to the FHS environment for extensions whose binaries need dependencies that are not already included. The same list is also used to determine the RPATH when automatically patching the ELF binaries, so one declaration covers both the FHS case and the patching case. ## Choosing a Node version and a set of install paths Two options control what the service works with. The first is nodejsPackage. By default VS Code Server installs the version of Node.js it needs, and the service automatically patches it, but if you want to minimize disk space or use a specific version of Node.js you can specify which Nix package it should use. ```nix { services.vscode-server.nodejsPackage = pkgs.nodejs-16_x; } ``` When enableFHS is set to true it will always require a Nix package for Node.js, though you are not required to set it, as it will default to the latest version used by VS Code. The author is honest about the risk in that default, in a disclaimer worth reading before you rely on it. The disclaimer says they are not a very active user of this extension, or even of NixOS at the moment, so the default can be out of date, and having it as an option is a workaround until the default gets updated. That is a maintainer telling you that the automatic path needs checking, and it is the reason to pin nodejsPackage explicitly if you care about reproducibility. The second is installPath, and it handles the case where you run more than one flavour of VS Code Server. The installation path is configurable, and you can specify either a single path as a string or multiple paths as a list, so that multiple installations such as stable, OSS and insider builds can all be monitored and automatically fixed. ```nix # Multiple paths (list) { services.vscode-server.installPath = [ "$HOME/.vscode-server" "$HOME/.vscode-server-oss" "$HOME/.vscode-server-insiders" ]; } ``` And string values are automatically coerced to a single element list for backwards compatibility, so old configurations keep working. ## postPatch, and the two troubleshooting notes There is one escape hatch for doing your own thing, and it is deliberately narrow. The postPatch option runs a shell script after the patching is done, and the README is explicit about the scope: the goal of this project is to make VS Code Server work with NixOS, anything more is outside of the scope of the project, but if you want additional things to be done you can use this hook. ```nix { services.vscode-server.postPatch = '' bin_dir=$1 # $bin_dir (vscode 1.105.1) is something like # ~/.vscode-server/cli/servers/Stable-7d842fb85a0275a4a8e4d7e040d2625abbf7f084/server # ... ''; } ``` The script receives the bin directory as its first argument, and the comment shows what that path looks like in practice, a directory under the cli/servers/Stable-/server hierarchy. That path shape changes between VS Code releases, which is a reason to keep anything you write in here defensive. The Troubleshooting section covers two things. The first is not really an issue with this project per se, but with systemd user services in NixOS in general: after updating it can be necessary to first disable the service again, which removes the symlink to the old version, and then enable and start it again. ```bash systemctl --user disable auto-fix-vscode-server.service ``` The second is a specific connection failure. If the remote SSH session fails with the error Failed to connect to the remote extension host server, with the text Connecting with SSH timed out, the fix is to add a setting to your VS Code settings json. ```json "remote.SSH.useLocalServer": false, ``` That was tested on VS Code version 1.63.2, connecting to the NixOS remote from a MacOS host. ## Conclusion Adopt nixos-vscode-server if you run VS Code Server against a NixOS machine and the bundled Node.js fails because of hardcoded paths, and you want that fixed by the system configuration rather than by hand. Do not adopt it as a general VS Code Server installer, since the README says the goal is to make VS Code Server work with NixOS and that anything more is outside the scope of the project. Before you enable it, read the service enablement steps, which are separate from the module configuration, and decide whether you want the FHS environment, since it changes terminal and SUID behaviour. ## FAQ ### Why does VS Code Server not work on NixOS without this module? The NodeJS supplied by VS Code by default cannot be used within NixOS because of missing hardcoded paths, so the module replaces it with a symlink to a compatible NodeJS version that does work under NixOS. ### How do I enable the vscode-server service for a user on NixOS? After adding the module you have to manually enable the service for each user with systemctl --user enable auto-fix-vscode-server.service. The message about the unit having no installation config can be safely ignored, and the service will start automatically after reboot or you can start it yourself. ### What does services.vscode-server.enableFHS do? It enables a Filesystem Hierarchy Standard compatible environment so that binaries supplied by extensions work in NixOS without patching them. The README notes downsides such as problematic support for SUID wrappers and terminals behaving differently from a normal SSH connection, which is why it is not enabled by default. ### Can I use a specific Node.js version with nixos-vscode-server? Yes. The nodejsPackage option specifies which Nix package for Node.js the service should use, which is useful to minimize disk space or to pin a version, and it is required when enableFHS is set to true. The same extraRuntimeDependencies list is also used to determine the RPATH when patching the ELF binaries. ## Sources - [Issues](https://github.com/nix-community/nixos-vscode-server/issues) - [License: MIT](https://github.com/nix-community/nixos-vscode-server/blob/master/LICENSE) - [nix-community/nixos-vscode-server on GitHub](https://github.com/nix-community/nixos-vscode-server) - [README](https://github.com/nix-community/nixos-vscode-server/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nix-community-nixos-vscode-server