NixOS Wiki

Zed: Difference between revisions

← Older edit
VisualWikitext
Picnoir (talk | contribs)
moderator
6 edits
No edit summary
Layer-09 (talk | contribs)
174 edits
mNo edit summary
 
(25 intermediate revisions by 11 users not shown)
Line 1: Line 1:
== Zed Editor ==
<languages/>
Zed is a graphical text editor focusing on speed and collaborative editing.
{{infobox application
  |name=Zed
  |image=Zed_Editor_Logo.png
  |type=Source-code Editor
  |developer=Zed Industries
  |predecessor=Atom
  |status=Active
  |license=[https://www.gnu.org/licenses/agpl-3.0.html AGPL], [https://www.gnu.org/licenses/gpl-3.0.html GPL], [https://www.apache.org/licenses/LICENSE-2.0 Apache License]
  |os=Cross-platform (Linux, macOS, Windows)
  |platform=Desktop
  |programmingLanguage=Rust
  |website=[https://zed.dev zed.dev]
  |github=zed-industries/zed
  |bugTracker=[https://github.com/zed-industries/zed/issues GitHub Issues]
  |documentation=[https://zed.dev/docs Zed Documentation]
}}
<translate>
<!--T:1-->
[https://zed.dev Zed]<ref>Zed Industries, "Zed", Official Website, Accessed October 2025. https://zed.dev</ref> is a collaborative, GPU-accelerated text editor developed by Zed Industries. It combines fast local editing with real-time multiplayer features and ships with batteries-included tooling for popular programming languages.
</translate>
<translate>
<!--T:2-->
The editor provides native builds for Linux, including Nixpkgs packages and a reproducible flake. Hardware acceleration requires a GPU with Vulkan support; systems without Vulkan can fall back to emulation via tools such as [https://github.com/nix-community/nixGL nixGL].<ref>Zed Industries, "Linux", Zed Documentation, Accessed October 2025. https://zed.dev/docs/linux</ref>
</translate>


Its Linux support is fairly recent, the NixOS support even more so.
<translate>
== Installation == <!--T:3-->


=== LSP Support ===
==== Shell ==== <!--T:4-->
By default, Zed will try to download pre-build LSP servers in <code>~/.local/share/zed/languages/</code>. This obviously won't work for NixOS.
</translate>
{{code|lang=bash|line=no|1=$ nix-shell -p zed-editor}}
<translate>
<!--T:5-->
The <code>zed-editor</code> package is available in Nixpkgs from channel 24.11 onward. The command above provides <code>zed-editor</code> in the current shell session without modifying any configuration files.


There's sadly no way to inject those from $PATH for now. Worse, the way to point to the language server is language-specific, there is no global configuration flag for now.
<!--T:6-->
The package installs both desktop launchers and a CLI entry point aliased to <code>zeditor</code>, mirroring the upstream binary name.


The following sections contain some language-specific setup working on NixOS.
==== System setup ==== <!--T:7-->
</translate>
{{code|lang=nix|line=no|1=# In /etc/nixos/configuration.nix
environment.systemPackages = [
  pkgs.zed-editor
];


==== Rust-analyzer ====
# In home-manager configuration (home.nix)
Here, we'll assume rust-analyzer is globally installed in your system profile at <code>/run/current-system/sw/bin/rust-analyzer</code>. You may want to adapt this path in the following code snippet to something more relevant to your use case.<syntaxhighlight lang="json">
home.packages = [
"lsp": {
  pkgs.zed-editor
  "rust-analyzer": {
];
    "binary": {
}}
<translate>
<!--T:8-->
Rebuild your system or Home Manager profile to make Zed available persistently. On NixOS, run <code>sudo nixos-rebuild switch</code>; for Home Manager, run <code>home-manager switch</code>.


      "path": "/run/current-system/sw/bin/rust-analyzer",
==== Flake ==== <!--T:9-->
    },
 
  }
<!--T:10-->
}
Zed maintains an official flake for tracking the latest upstream build. This approach is useful if you need features that have not yet reached stable Nixpkgs.
</syntaxhighlight>
</translate>
[[Category:Software]]
{{code|lang=nix|line=no|1=inputs.zed.url = "github:zed-industries/zed";
 
outputs = { self, nixpkgs, zed, ... }@inputs: let
  system = "x86_64-linux";
  pkgs = import nixpkgs { inherit system; };
in {
  packages.${system}.zed-latest = zed.packages.${system}.default;
};}}
<translate>
<!--T:11-->
Build the flake package with <code>nix build .#zed-latest</code> or expose it in your configuration with the appropriate overlay.
</translate>
{{Warning|Zed requires hardware-accelerated Vulkan. On systems without supported drivers, use <code>nixGL</code> or home-manager's <code>nixGL.vulkan.enable {{=}} true;</code> to provide the necessary libraries.}}
<translate>
<!--T:12-->
Providing Vulkan through <code>nixGL</code> can be more consistent than relying on host distribution packages, especially on non-NixOS systems where Wayland and X11 stacks differ in their Vulkan capabilities.
 
== Configuration == <!--T:13-->
 
<!--T:14-->
Zed stores its configuration in JSON files under <code>~/.config/zed</code>. Home Manager can manage these settings declaratively.
 
==== Basic ==== <!--T:15-->
</translate>
{{code|lang=nix|line=no|1=programs.zed-editor = {
  enable = true;
  extensions = [ "nix" "toml" "rust" ];
  userSettings = {
    theme = {
      mode = "system";
      dark = "One Dark";
      light = "One Light";
    };
    hour_format = "hour24";
    vim_mode = true;
  };
};}}
<translate>
<!--T:16-->
The configuration above enables Zed via Home Manager, installs a small set of extensions, and synchronises the theme with the desktop appearance.
 
==== Advanced ==== <!--T:17-->
</translate>
{{code|lang=nix|line=no|1=
programs.zed-editor = {
  enable = true;
 
  # This populates the userSettings "auto_install_extensions"
  extensions = [ "nix" "toml" "elixir" "make" ];
 
  # Everything inside of these brackets are Zed options
  userSettings = {
    assistant = {
      enabled = true;
      version = "2";
      default_open_ai_model = null;
 
      # Provider options:
      # - zed.dev models (claude-3-5-sonnet-latest) requires GitHub connected
      # - anthropic models (claude-3-5-sonnet-latest, claude-3-haiku-latest, claude-3-opus-latest) requires API_KEY
      # - copilot_chat models (gpt-4o, gpt-4, gpt-3.5-turbo, o1-preview) requires GitHub connected
      default_model = {
        provider = "zed.dev";
        model = "claude-3-5-sonnet-latest";
      };
 
      # inline_alternatives = [
      #  {
      #    provider = "copilot_chat";
      #    model = "gpt-3.5-turbo";
      #  }
      # ];
    };
 
    node = {
      path = lib.getExe pkgs.nodejs;
      npm_path = lib.getExe' pkgs.nodejs "npm";
    };
 
    hour_format = "hour24";
    auto_update = false;
 
    terminal = {
      alternate_scroll = "off";
      blinking = "off";
      copy_on_select = false;
      dock = "bottom";
      detect_venv = {
        on = {
          directories = [ ".env" "env" ".venv" "venv" ];
          activate_script = "default";
        };
      };
      env = {
        TERM = "alacritty";
      };
      font_family = "FiraCode Nerd Font";
      font_features = null;
      font_size = null;
      line_height = "comfortable";
      option_as_meta = false;
      button = false;
      shell = "system";
      # shell = {
      #  program = "zsh";
      # };
      toolbar = {
        title = true;
      };
      working_directory = "current_project_directory";
    };
 
    lsp = {
      rust-analyzer = {
        binary = {
          # path = lib.getExe pkgs.rust-analyzer;
          path_lookup = true;
        };
      };
 
      nix = {
        binary = {
          path_lookup = true;
        };
      };
 
      elixir-ls = {
        binary = {
          path_lookup = true;
        };
        settings = {
          dialyzerEnabled = true;
        };
      };
    };
 
    languages = {
      "Elixir" = {
        language_servers = [ "!lexical" "elixir-ls" "!next-ls" ];
        format_on_save = {
          external = {
            command = "mix";
            arguments = [ "format" "--stdin-filename" "{buffer_path}" "-" ];
          };
        };
      };
 
      "HEEX" = {
        language_servers = [ "!lexical" "elixir-ls" "!next-ls" ];
        format_on_save = {
          external = {
            command = "mix";
            arguments = [ "format" "--stdin-filename" "{buffer_path}" "-" ];
          };
        };
      };
    };
 
    vim_mode = true;
 
    # Tell Zed to use direnv and direnv can use a flake.nix environment
    load_direnv = "shell_hook";
    base_keymap = "VSCode";
 
    theme = {
      mode = "system";
      light = "One Light";
      dark = "One Dark";
    };
 
    show_whitespaces = "all";
    ui_font_size = 16;
    buffer_font_size = 16;
  };
};
}}
<translate>
<!--T:18-->
This example adds language servers to the FHS sandbox, enables the bundled assistant, configures the terminal, and ensures remote server binaries are provided declaratively.
 
<!--T:19-->
The <code>userSettings</code> and <code>userKeyMaps</code> options translate directly into JSON. The <code>extraPackages</code> option includes additional Nixpkgs in the FHS environment, useful for LSP servers (e.g., <code>pkgs.nixd</code>) or optional tools (e.g., <code>pkgs.shellcheck</code> for the Basher LSP).
 
<!--T:20-->
Home Manager renders <code>settings.json</code> as read-only, which prevents Zed's GUI from saving most preference changes, including AI provider selection. Plan to manage long-term settings declaratively or temporarily disable the module when editing interactively.
 
<!--T:21-->
Only the initial extension list can be defined declaratively; additional extensions installed through the GUI are stored within Zed's writable data directories and do not appear in <code>userSettings</code>. This follows a similar model to VSCode, where extensions require external binaries downloaded at runtime.
</translate>
 
== LSP support ==
<translate>
<!--T:22-->
Zed downloads language servers into <code>~/.local/share/zed/languages/</code>, which is read-only on NixOS. Instead, use declarative methods to supply LSP binaries.
</translate>
<translate>
<!--T:23-->
Check <strong>LSP Logs → Server Info</strong> to confirm which binaries are running. Prefer language servers packaged in Nixpkgs so that dependencies are resolved within the Nix store.
</translate>
 
==== Nix-ld (recommended) ====
<translate>
<!--T:24-->
Enable [[FAQ#I've downloaded a binary, but I can't run it, what can I do?|<code>nix-ld</code>]] so prebuilt language servers can resolve dynamic libraries without wrapping.
</translate>
 
==== FHS wrapper ====
<translate>
<!--T:25-->
Use <code>pkgs.zed-editor.fhsWithPackages</code> to extend the FHS environment with additional system libraries when a language server requires them.
</translate>
{{code|lang=nix|line=no|1=pkgs.zed-editor.fhsWithPackages (pkgs: with pkgs; [ openssl zlib ])}}
<translate>
<!--T:26-->
Remember that language servers started inside the wrapper do not automatically inherit tools from ad-hoc shells; include every dependency declaratively.
</translate>
 
==== Bring your own LSP servers ====
<translate>
<!--T:27-->
Newer versions of Zed can detect LSP servers installed in <code>PATH</code> and prefer local versions over automatically downloaded ones. Install LSP servers globally or provide them through nix shell.
</translate>
<translate>
<!--T:28-->
Nixpkgs versions of tools may be required for development on NixOS, especially for the C/C++ ecosystem. Check <strong>LSP Logs → Server Info</strong> to see which binaries are running.
</translate>
<translate>
<!--T:29-->
If automatic detection doesn't work, specify the path manually in your Zed configuration:
</translate>
{{code|lang=json|line=no|1={
  "lsp": {
    "rust-analyzer": {
      "binary": {
        "path": "/run/current-system/sw/bin/rust-analyzer"
      }
    }
  }
}
}}
<translate>
<!--T:30-->
Adjust the path for each language server you manage. The example above assumes rust-analyzer is installed in your system profile.
</translate>
== Remote server ==
<translate>
<!--T:31-->
Zed uploads a versioned remote server binary to <code>~/.zed_server</code> on the target host. The Nixpkgs package exposes the matching binary via the <code>remote_server</code> output.
</translate>
<translate>
<!--T:32-->
When you connect to a remote machine, the client either downloads a matching server binary from upstream or pushes a local copy if <code>"upload_binary_over_ssh": true</code> is enabled. Connections fail if the versions diverge.
</translate>
{{code|lang=nix|line=no|1=home.file.".zed_server" = {
  source = "${pkgs.zed-editor.remote_server}/bin";
  recursive = true;
};}}
<translate>
<!--T:33-->
The <code>recursive = true;</code> setting keeps the directory writable while symlinking individual binaries, allowing Zed to add new versions when needed. This is necessary because the <code>~/.zed_server</code> folder is also used when external clients connect to the current system as a remote.
</translate>
<translate>
<!--T:34-->
Alternatively, use Home Manager's built-in option for simpler setup:
</translate>
{{code|lang=nix|line=no|1=programs.zed-editor = {
  enable = true;
  installRemoteServer = true;
};}}
<translate>
<!--T:35-->
To restrict remote clients to a specific server version, set <code>recursive = false;</code> to make the entire folder read-only. Zed refuses to connect if it cannot provision the required binary, so document the restriction for collaborators.
</translate>
 
== Tips and tricks ==
 
==== Vulkan diagnostics ====
{{code|lang=bash|line=no|1=$ vulkaninfo --summary}}
<translate>
<!--T:36-->
Run the command above to check your Vulkan support before launching Zed. Install <code>vulkan-tools</code> if the command is not available. On non-NixOS systems, you may need to wrap Zed with <code>nixGLVulkan</code> from the nixGL package.
</translate>
 
==== Preinstall extensions ====
{{code|lang=json|line=no|1={
  "extensions": [
    "nix",
    "toml",
    "elixir"
  ]
}
}}
<translate>
<!--T:37-->
Declaratively listing extensions ensures they are installed automatically on new systems while still allowing additional extensions to be added interactively.
</translate>
 
==== Synchronise settings across machines ====
<translate>
<!--T:38-->
Store the entire <code>~/.config/zed</code> directory in a version-controlled dotfiles repo or manage it with Home Manager to keep settings consistent across hosts.
</translate>
 
== Troubleshooting ==
 
==== Zed fails to start without Vulkan ====
<translate>
<!--T:39-->
If the GUI refuses to launch, confirm that <code>vulkan-tools</code> reports a working ICD. Use <code>nixGL</code> or vendor packages that supply Vulkan drivers for your GPU.
</translate>
 
==== Remote collaboration disconnects ====
<translate>
<!--T:40-->
Ensure the remote server binary matches the client version. Re-run <code>home-manager switch</code> or update the symlink in <code>~/.zed_server</code> if the versions diverge after an update.
</translate>
 
==== Language server missing binaries ====
<translate>
<!--T:41-->
When Zed reports missing tools, add the required executables to <code>programs.zed-editor.extraPackages</code> or wrap the server using <code>pkgs.writeShellApplication</code>.
</translate>
 
== See also ==
* <translate>
<!--T:42-->
[[Home Manager]] – Manage Zed configuration declaratively
</translate>
* <translate>
<!--T:43-->
[[Graphics#Vulkan]] – Set up Vulkan on NixOS systems
</translate>
* <translate>
<!--T:44-->
[https://search.nixos.org/options?query=zed-editor NixOS options search for Zed]
</translate>
 
== References ==
<references/>
 
[[Category:Applications]]
[[Category:Text Editor]]
Retrieved from "https://wiki.nixos.org/wiki/Zed"