Zed — User Guide

Zed is a high-performance, GPU-accelerated code editor built in Rust on a custom UI framework called GPUI. It runs natively on macOS, Linux, and Windows, delivering sub-millisecond input latency and smooth rendering through direct GPU composition. Zed combines the speed of a minimal editor with the capabilities of a full IDE: an AI-powered coding agent, real-time collaboration, integrated terminal, built-in Git UI, Vim and Helix modal editing, Language Server Protocol support, edit predictions, a WASM-based extension system, remote development over SSH, dev containers, a debugger, REPL notebooks, and a command palette that puts every feature at your fingertips.

This guide covers everything you need to use Zed productively, from first launch through advanced workflows. For architecture details, deployment configuration, and internals, see the companion Admin Guide.

1. Quick Start

Get from zero to editing in under two minutes.

1.1 Install

macOS:

brew install --cask zed

Linux (stable):

curl -f https://zed.dev/install.sh | sh

Windows:

Download the installer from zed.dev or use:

winget install Zed.Zed

1.2 Launch and Open a Project

# Open a directory as a workspace
zed ~/projects/my-app

# Open a specific file at a line
zed src/main.rs:42

# Open multiple files
zed file1.rs file2.rs file3.rs

1.3 The Five Commands You Need First

The Command Palette is your universal entry point. If you forget a keybinding, open the palette and type what you want to do.

Tip

You can type partial, out-of-order fragments in the Command Palette. Typing "term tog" matches "Terminal: Toggle". Muscle-memory keybindings will come later — the palette gets you there immediately.

1.4 Set Your Preferences

Open settings (Ctrl+Alt+, / Cmd+,) and make it yours:

{
  "theme": {
    "mode": "dark",
    "dark": "One Dark",
    "light": "One Light"
  },
  "buffer_font_size": 15,
  "vim_mode": false,
  "base_keymap": "VSCode"
}

Zed applies changes immediately on save — no restart needed.

2. Installation

2.1 System Requirements

Zed requires a GPU that supports the graphics APIs used by GPUI:

Important

On Linux, Zed requires a working Vulkan driver. If Zed fails to launch with a GPU-related error, install the appropriate Vulkan packages for your GPU vendor (mesa-vulkan-drivers for AMD/Intel, nvidia-vulkan-icd-ci for NVIDIA on Debian-based systems). Wayland and X11 are both supported.

2.2 Installation Methods

macOS

Homebrew (recommended):

brew install --cask zed

Direct download: Grab the .dmg from zed.dev, open it, drag Zed to Applications.

Linux

Install script (recommended):

curl -f https://zed.dev/install.sh | sh

This installs the zed binary and sets up the CLI. The script supports both stable and preview channels.

Flatpak, AppImage, and distro packages are also available through community channels.

Windows

WinGet:

winget install Zed.Zed

Direct download: Installer available from zed.dev.

2.3 CLI Installation

The zed CLI is the primary way to open files and directories from your terminal. On macOS, install the CLI from within Zed via the Command Palette: search for "cli: install" and run it. On Linux, the install script sets up the CLI automatically. On Windows, the installer adds zed to your PATH.

2.4 Updating

Zed auto-updates by default. Control this behavior:

{
  "auto_update": true
}

Set to false to manage updates manually. When disabled, check for updates through the Command Palette ("zed: check for updates").

2.5 Uninstalling

# Linux and macOS
zed --uninstall

# Or remove manually
# macOS: delete /Applications/Zed.app and ~/Library/Application Support/Zed/
# Linux: remove ~/.local/bin/zed and ~/.config/zed/

2.6 Data Directories

Zed stores configuration and data in platform-standard locations:

Override the data directory with the --user-data-dir flag:

zed --user-data-dir /custom/path ~/projects/my-app

2.7 Telemetry

Zed collects diagnostics and usage metrics by default. Disable either or both:

{
  "telemetry": {
    "diagnostics": false,
    "metrics": false
  }
}

3. Configuration

Zed uses JSON files for settings and keybindings. Changes take effect immediately on save — no restart or reload required.

3.1 Settings Files

Global settings apply everywhere. Edit them with Ctrl+Alt+, (macOS: Cmd+,) or via Command Palette ("zed: open settings").

Local (project) settings live in .zed/settings.json at the root of your workspace. They override global settings for that project only — ideal for team-wide formatting rules, language-specific overrides, or project-specific LSP configuration.

3.2 Theme

{
  "theme": {
    "mode": "system",
    "light": "One Light",
    "dark": "One Dark"
  }
}

The mode field accepts "system" (follows OS dark/light preference), "dark", or "light". The light and dark fields select which theme to use in each mode. Browse and install community themes through the Extensions panel.

3.3 Fonts

{
  "buffer_font_family": ".ZedMono",
  "buffer_font_size": 15,
  "buffer_line_height": "comfortable",
  "ui_font_family": ".ZedSans",
  "ui_font_size": 16
}

3.4 Base Keymap

{
  "base_keymap": "VSCode"
}

Available keymaps: VSCode, Atom, JetBrains, SublimeText, TextMate, Emacs, Cursor, None.

This sets the starting point for keybindings. You can then override individual bindings in your keymap.json file (open via Command Palette: "zed: open keymap").

3.5 Editor Behavior

{
  "tab_size": 4,
  "hard_tabs": false,
  "soft_wrap": "none",
  "format_on_save": "on",
  "autosave": "off",
  "cursor_blink": true,
  "cursor_shape": "bar",
  "show_whitespaces": "selection",
  "current_line_highlight": "all",
  "colorize_brackets": false,
  "confirm_quit": false,
  "relative_line_numbers": "disabled",
  "show_completions_on_input": true,
  "inlay_hints": {
    "enabled": false
  }
}

Key behavior options explained:

3.6 Minimap

{
  "minimap": {
    "show": "never"
  }
}

Options: "auto" (shows on hover at scroll bar), "always", "never".

3.7 Terminal Settings

{
  "terminal": {
    "shell": "system",
    "dock": "bottom",
    "blinking": "terminal_controlled"
  }
}

The shell setting accepts "system" (uses your default shell) or a specific shell path. The dock position can be "bottom", "left", or "right".

3.8 Project Panel

{
  "project_panel": {
    "dock": "right",
    "default_width": 240
  }
}

Note

Zed docks the project panel on the right by default, which differs from most editors. If you prefer the traditional left-side file tree, set "project_panel": {"dock": "left"}.

3.9 Git Settings

{
  "git": {
    "inline_blame": {
      "enabled": true
    },
    "git_gutter": "tracked_files"
  }
}

Inline blame shows the author and commit message for the current line. The git gutter shows added/modified/deleted markers in the sign column for files tracked by Git.

3.10 AI and Agent Settings

{
  "disable_ai": false,
  "agent": {
    "enabled": true,
    "dock": "left",
    "default_model": {
      "provider": "zed.dev",
      "model": "claude-sonnet-4"
    }
  }
}

Set "disable_ai": true to turn off all AI features globally.

3.11 Edit Predictions

{
  "show_edit_predictions": true,
  "edit_predictions": {
    "provider": "zed"
  }
}

Providers: "zed" (default, uses Zed's cloud), "copilot", "codestral", "ollama", "open_ai_compatible_api".

3.12 Multi-Cursor Modifier

{
  "multi_cursor_modifier": "alt"
}

This controls which key you hold while clicking to place additional cursors. Options are "alt" (default) and "ctrl" / "cmd" depending on platform.

3.13 Startup Behavior

{
  "restore_on_startup": "last_session",
  "cli_default_open_behavior": "existing_window"
}

3.14 Language-Specific Overrides

Override any editor setting per language:

{
  "languages": {
    "Python": {
      "tab_size": 4,
      "format_on_save": "on",
      "hard_tabs": false
    },
    "Go": {
      "tab_size": 4,
      "hard_tabs": true,
      "format_on_save": "on"
    },
    "Markdown": {
      "soft_wrap": "preferred_line_length"
    }
  }
}

3.15 Custom Keybindings

Open the keymap file via Command Palette ("zed: open keymap"). Keybindings use a context system to scope bindings to specific views:

[
  {
    "context": "Editor && !VimControl",
    "bindings": {
      "ctrl-d": "editor::SelectNext"
    }
  },
  {
    "context": "Workspace",
    "bindings": {
      "ctrl-shift-t": "workspace::NewTerminal"
    }
  }
]

Tip

Use the Command Palette to discover the internal action names for any command. The palette shows both the human-readable label and the action identifier you need for custom keybindings.

4. Core Usage

4.1 The Workspace

When you open a directory with Zed, it becomes a workspace. The workspace is the fundamental unit of organization:

• The Project Panel (toggled via sidebar or Command Palette) shows the file tree
• Panes hold tabs — split horizontally or vertically with Ctrl+K then an arrow key
• The Status Bar at the bottom shows language, line/column, Git branch, and diagnostics
• Panels (terminal, agent, outline, etc.) dock to the bottom, left, or right

Opening Files

The file finder supports fuzzy matching: typing srm matches src/main.rs. Results are ranked by frecency (frequency + recency).

Tabs and Panes

• Click a file once in the Project Panel to preview it (italic title, replaced by the next preview)
• Double-click or edit to pin the tab
• Drag tabs between panes
• Ctrl+K then arrow key to split the current pane
• Ctrl+W / Cmd+W to close a tab

4.2 Editing

Multi-Cursor Editing

Hold Alt (configurable via multi_cursor_modifier) and click to place additional cursors. Other multi-cursor workflows:

Code Navigation

Find and Replace

Buffer Search (Ctrl+F): Search within the current file. Supports regex, case-sensitive, and whole-word modes via toggle buttons in the search bar.

Project Search (Ctrl+Shift+F): Search across all files in the workspace. Supports include/exclude glob patterns for filtering which files to search.

Code Actions and Refactoring

When a language server is active, code actions appear as lightbulb icons in the gutter or can be triggered from the context menu. Common actions include:

• Rename symbol (language server refactoring)
• Extract to function/variable
• Auto-import
• Quick fixes for diagnostics

Formatting

Format the current file with Ctrl+Shift+I. With "format_on_save": "on" (the default), formatting happens automatically every time you save.

Note

Formatting relies on a language server or formatter being available for the current language. If formatting does nothing, check that the appropriate extension is installed and the language server is running (visible in the status bar).

4.3 Language Server Protocol (LSP)

Zed uses LSP for language intelligence: completions, diagnostics, go-to-definition, hover info, code actions, and more. Language servers are typically installed automatically through extensions.

Diagnostics appear inline as squiggly underlines with severity-colored markers in the gutter. The diagnostics panel (toggle via Command Palette: "diagnostics: deploy") shows all workspace diagnostics in a filterable list.

Completions appear automatically as you type when "show_completions_on_input" is true (the default). Use Tab or Enter to accept, Escape to dismiss.

Inlay Hints show inline type annotations, parameter names, and other information from the language server. Enable them with:

{
  "inlay_hints": {
    "enabled": true
  }
}

4.4 Integrated Terminal

Toggle the terminal panel with Ctrl+`. Key capabilities:

• Multiple terminal tabs within the panel
• Clickable URLs and file paths (Ctrl+click)
• Shell integration for command tracking
• Configurable shell, font, and blinking behavior
• "terminal.dock": position at "bottom", "left", or "right"

Create a new terminal tab from the Command Palette ("workspace: new terminal") or the + button in the terminal panel.

4.5 Git Integration

Zed has built-in Git support without requiring an extension:

• Git Gutter: Added/modified/deleted indicators in the sign column for tracked files
• Inline Blame: Author and commit info displayed inline for the current line
• Uncommitted Changes: View a diff of your changes
• Staging: Stage and unstage individual files or hunks
• Branch Management: Switch, create, and delete branches

Access Git operations through the Command Palette (search "git") or the Git status indicators in the status bar.

Warning

There is a known issue where staging individual code blocks can cause a crash in certain edge cases (see upstream issue #54155). If you encounter this, stage the entire file instead.

4.6 Vim Mode

Enable Vim-style modal editing:

{
  "vim_mode": true
}

Vim mode implements standard Vim motions, operators, text objects, visual modes, and Ex commands. It builds on your base_keymap — Vim bindings take priority in Normal mode, while Insert mode falls through to your base keymap.

Key Vim features supported:

• Normal, Insert, Visual, Visual Line, Visual Block modes
• Motions: h/j/k/l, w/b/e, f/t, gg/G, 0/$, %, search (/ and ?)
• Operators: d, c, y, >, <, =
• Text objects: iw, aw, i", a", i(, a(, it, at, etc.
• Registers, marks, macros
• Ex commands (:w, :q, :e, :s, etc.)
• Surround operations (with vim-surround style bindings)

4.7 Helix Mode

For users who prefer Helix-style editing (selection-first, then action):

{
  "helix_mode": true
}

Helix mode implements Helix's selection-based modal editing model, where you first select text and then apply an action to the selection — the reverse of Vim's operator-motion model.

4.8 Edit Predictions

Edit predictions suggest multi-line edits as you type, powered by AI. Ghost text appears inline showing the predicted continuation or change.

{
  "show_edit_predictions": true,
  "edit_predictions": {
    "provider": "zed"
  }
}

Prediction mode can be set to "eager" (default, shows predictions proactively) or "subtle" (less intrusive).

Available providers:

4.9 AI Agent

The Agent is Zed's built-in AI coding assistant. It can read files, edit code, run terminal commands, search the web, and more.

Opening the Agent

Toggle the Agent panel with Ctrl+Shift+A or click the Agent icon in the sidebar. The default dock position is the left side.

Agent Profiles

Three built-in profiles control what the agent can do:

Agent Tools

In Write mode, the agent has access to these tools:

• read_file — Read file contents
• edit_file — Make targeted edits to files
• save_file — Save files to disk
• restore_file_from_disk — Revert changes
• create_directory — Create directories
• delete_path — Delete files or directories
• move_path — Move or rename files
• copy_path — Copy files
• list_directory — List directory contents
• find_path — Find files by name pattern
• grep — Search file contents
• terminal — Run shell commands
• open — Open files in the editor
• fetch — Fetch URLs
• search_web — Search the web
• diagnostics — Get LSP diagnostics
• spawn_agent — Create sub-agents for parallel work
• thinking — Extended reasoning
• update_plan — Track progress on complex tasks
• now — Get current date/time

Tool Permissions

{
  "agent": {
    "tool_permissions": {
      "default": "confirm"
    }
  }
}

The default is "confirm" — the agent asks before executing tools. You can set this to "allow" for automatic execution or configure per-tool permissions.

Caution

Setting "tool_permissions": {"default": "allow"} gives the agent unrestricted ability to modify files, run terminal commands, and delete paths without confirmation. Use this only in isolated or disposable environments.

Default Model

{
  "agent": {
    "default_model": {
      "provider": "zed.dev",
      "model": "claude-sonnet-4"
    }
  }
}

You can switch models per-conversation from the model picker in the Agent panel.

4.10 Collaboration

Zed supports real-time collaborative editing. Multiple people can edit the same workspace simultaneously with live cursors, selections, and changes.

Calls

Start or join a call through the Collaboration panel. Call settings:

{
  "calls": {
    "mute_on_join": false,
    "share_on_join": false
  }
}

When "share_on_join" is true, your project is automatically shared when you join a call. Otherwise, you explicitly share via the Collaboration panel.

Channels

Channels provide persistent spaces for collaboration. Channel members can join shared projects, chat, and work together. Channels support nested hierarchies for organizing teams and projects.

4.11 Extensions

Zed's extension system is WASM-based — extensions run in a sandboxed WebAssembly environment for security and performance. Extensions can provide:

• Languages — syntax highlighting, indentation rules, bracket pairs
• Themes — color schemes for the editor
• Language Servers — LSP integrations for language intelligence
• Slash Commands — custom commands for the Agent
• Context Servers — additional context sources for AI

Browse and install extensions through the Extensions panel (Command Palette: "zed: extensions"). The HTML extension auto-installs on first launch.

4.12 Remote Development

Zed supports editing files on remote machines over SSH. The remote development workflow installs a lightweight Zed server on the remote host and streams the UI back to your local machine.

# Open a remote project
zed ssh://user@hostname/path/to/project

Dev Containers

Zed can open projects inside dev containers for reproducible development environments:

zed --dev-container /path/to/project

This uses the project's .devcontainer/devcontainer.json configuration to build and connect to the container.

4.13 Debugger

Zed includes an integrated debugger that supports the Debug Adapter Protocol (DAP):

Set breakpoints by clicking in the gutter or pressing F9. Configure debug launch configurations through .zed/debug.json or the Debug panel.

4.14 REPL (Jupyter Notebooks)

Zed supports Jupyter-style interactive computing. You can run code cells in-editor and see results inline, connecting to Jupyter kernels for Python, Julia, R, and other languages.

4.15 Outline View

The Outline panel shows a structured view of the current file's symbols — functions, classes, structs, constants — for quick navigation. Access it through the Command Palette ("outline: toggle") or use Ctrl+Shift+O to jump to a symbol.

4.16 Breadcrumbs

The breadcrumb bar at the top of each editor pane shows the file path and current symbol context. Click any segment to navigate to that level.

5. Common Tasks

5.1 Opening and Managing Projects

Open a Folder as a Workspace

zed /path/to/project

Or use File > Open Folder from within Zed.

Add a Folder to the Current Workspace

zed -a /path/to/additional/folder

The -a / --add flag adds the directory to the current workspace rather than replacing it.

Open in a New Window

zed -n /path/to/project

Forces a new window even if Zed is already running.

Open in an Existing Window

zed -e /path/to/file

The -e / --existing flag opens the path in an existing Zed window.

Pipe stdin Into Zed

cat output.log | zed -

The - argument tells Zed to read from standard input and open the content in a new buffer.

5.2 File Navigation Recipes

Jump to a File by Name

Press Ctrl+P and type part of the filename. The fuzzy matcher handles out-of-order fragments:

• Type cmprs to find components.rs
• Type src/lib to narrow by path
• Type mod.rs to see all module files

Jump to a Symbol in the Current File

Ctrl+Shift+O opens the symbol picker. Type to filter by symbol name — functions, classes, structs, enums, constants.

Jump to a Line Number

Ctrl+G, type the line number, press Enter.

Open a File at a Specific Position from the CLI

zed src/main.rs:42:10

Opens src/main.rs at line 42, column 10.

5.3 Search and Replace

Find in Current File

1. Ctrl+F opens the search bar
2. Type your search term
3. Use the toggle buttons for: regex (.*), case sensitivity (Aa), whole word (\bW\b)
4. Enter to go to next match, Shift+Enter for previous
5. Expand to replace with the > arrow or Ctrl+H

Find Across All Files

1. Ctrl+Shift+F opens Project Search
2. Type your search term
3. Use include/exclude patterns to filter (e.g., include *.rs, exclude target/)
4. Results appear grouped by file with surrounding context
5. Click any result to jump to that location

Find and Replace Across Files

In Project Search, toggle the replace field, type the replacement, and use "Replace All" to apply across all matches.

5.4 Multi-Cursor Workflows

Select All Occurrences of a Word and Rename

1. Place cursor on a word
2. Ctrl+Shift+L to select all occurrences
3. Type the replacement — all occurrences update simultaneously

Add Cursors to Consecutive Lines

1. Ctrl+Alt+Down to add a cursor on the line below (repeat as needed)
2. Edit on all lines at once

Select Next Occurrence Incrementally

1. Select a word or text
2. Ctrl+D to also select the next occurrence
3. Repeat Ctrl+D for more occurrences
4. Ctrl+U to undo the last selection if you skip one

5.5 Split Pane Workflows

Side-by-Side Editing

1. Open the first file
2. Ctrl+K then Right to split the pane
3. Open the second file in the new pane with Ctrl+P

Three-Way View

1. Split right: Ctrl+K Right
2. Focus the right pane
3. Split down: Ctrl+K Down
4. Now you have an L-shaped layout

Compare Two Files (Diff)

zed --diff file1.rs file2.rs

Opens a diff view comparing the two files (or directories) side by side.

5.6 Terminal Workflows

Run a Build Command

1. Ctrl+` to open the terminal
2. Run your build: cargo build, npm run build, make, etc.
3. Errors with file paths and line numbers are often clickable

Multiple Terminal Sessions

Click + in the terminal panel to create additional terminal tabs. Each runs an independent shell session.

Terminal Alongside Editor

With "terminal.dock": "bottom" (default), the terminal sits below your editor panes. Adjust the panel height by dragging the divider. Use "terminal.dock": "right" to put it side-by-side with the editor.

5.7 Git Workflows

Check What Changed

Open the Command Palette and search "git" to access:

• View uncommitted changes (diff view)
• Stage/unstage files
• View file history

Stage and Commit

1. Open the Git panel
2. Review changed files
3. Stage individual files or all changes
4. Write a commit message
5. Commit

View Blame

Alt+G B toggles inline Git blame for the current file. Each line shows the author, date, and commit message.

Switch Branches

Use the branch picker in the status bar or Command Palette to switch, create, or delete branches.

5.8 Vim Recipes

Enable Vim Mode

{
  "vim_mode": true
}

Common Vim Workflows in Zed

5.9 Formatting Workflows

Format on Save

Enabled by default:

{
  "format_on_save": "on"
}

Format Manually

Ctrl+Shift+I formats the current file using the active language server or formatter.

Per-Language Formatter Configuration

{
  "languages": {
    "JavaScript": {
      "format_on_save": "on"
    },
    "Rust": {
      "format_on_save": "on"
    }
  }
}

5.10 Working with Large Projects

Exclude Directories from Search

In your .zed/settings.json:

{
  "file_scan_exclusions": [
    "node_modules",
    "target",
    "dist",
    ".git"
  ]
}

This excludes directories from both the file finder and project search.

5.11 Using Code Actions

When a language server provides code actions (auto-import, quick fix, refactoring), a lightbulb icon appears in the gutter. Click it or use the keyboard shortcut to see available actions. Common code actions:

• Fix missing imports
• Apply suggested fixes for diagnostics
• Extract function/variable
• Inline variable
• Convert between syntax forms

5.12 Working with Diagnostics

View All Diagnostics

Open the Diagnostics panel via Command Palette ("diagnostics: deploy"). Diagnostics are grouped by file and severity (error, warning, info, hint).

Navigate Between Errors

Use F8 / Shift+F8 (or the keybinding for "go to next/previous diagnostic") to jump between diagnostic locations in the current file.

5.13 Snippet Workflows

Language servers and extensions provide code snippets. When a completion item is a snippet, accepting it inserts the template with tab stops. Press Tab to move between placeholder positions.

5.14 Bracket Pair Colorization

Enable colored bracket pairs to visually match nested brackets:

{
  "colorize_brackets": true
}

5.15 Autosave Configurations

Save when switching windows:

{
  "autosave": "on_window_change"
}

Save when the editor loses focus:

{
  "autosave": "on_focus_change"
}

Save after a delay (e.g., 1 second):

{
  "autosave": {
    "after_delay": {
      "milliseconds": 1000
    }
  }
}

Note

Autosave does not currently work in Uncommitted Changes views (known issue #53413). Files edited in the main editor buffer are saved correctly.

5.16 Using the Agent for Code Tasks

Ask the Agent to Explain Code

1. Open the Agent panel (Ctrl+Shift+A)
2. Switch to the Ask profile (read-only)
3. Type: "Explain what src/main.rs does"
4. The agent reads the file and provides an explanation

Have the Agent Refactor Code

1. Open the Agent panel
2. Ensure the Write profile is active
3. Type: "Refactor the process_data function in src/lib.rs to use iterators instead of for loops"
4. Review the proposed changes before accepting

Spawn Sub-Agents for Parallel Work

The agent can spawn sub-agents to work on independent tasks simultaneously using the spawn_agent tool. This is useful for large refactoring tasks that touch multiple files.

5.17 Debug a Program

1. Create a .zed/debug.json configuration for your project
2. Set breakpoints by pressing F9 on the desired lines
3. Press F4 to start debugging
4. Use the debug toolbar: Step Over (F10), Step Into (F11), Step Out (Shift+F11)
5. Inspect variables in the debug panel

5.18 Run REPL Cells

1. Open a Python (or Julia, R, etc.) file
2. Write code in cells (delimited by # %% or language-specific markers)
3. Run the current cell with the run button or keybinding
4. Output appears inline below the cell

5.19 Remote Editing Over SSH

# Connect to a remote machine
zed ssh://user@hostname/path/to/project

Zed installs a lightweight server component on the remote host. Your local Zed instance renders the UI while all file operations happen remotely.

5.20 Dev Container Workflow

# Open a project with dev container support
zed --dev-container /path/to/project

Zed reads the .devcontainer/devcontainer.json file, builds the container (if needed), and connects to it for a fully isolated development environment.

5.21 CLI Wait Mode

# Use Zed as your Git editor
export EDITOR="zed --wait"
git commit

The --wait (-w) flag makes the zed command block until you close the opened file — essential for use as $EDITOR with Git, crontab -e, and similar tools.

Warning

There is a known issue (#54203) where zed --wait may not block correctly when Zed is already running. If you experience this, try closing other Zed instances first.

5.22 View System Specs

zed --system-specs

Prints GPU, OS, and Zed version information — useful for bug reports.

5.23 Run Zed in Foreground Mode

zed --foreground

Runs Zed attached to the terminal with log output visible. Useful for debugging startup issues.

5.24 Working with Extensions

Install an Extension

1. Open Command Palette (Ctrl+Shift+P)
2. Search "zed: extensions"
3. Browse or search for the extension
4. Click Install

Discover Language Extensions

Search for your language in the Extensions panel. For example, installing the Python extension typically sets up the language server (Pyright or similar), syntax highlighting, and formatting support automatically.

5.25 Workspace Trust and Project Settings

Create a .zed/settings.json file in your project root to share settings with your team:

{
  "tab_size": 2,
  "hard_tabs": false,
  "format_on_save": "on",
  "languages": {
    "TypeScript": {
      "tab_size": 2
    }
  }
}

These settings are automatically applied when anyone opens the project in Zed, ensuring consistent formatting across the team.

5.26 Using the Diff View

# Compare two files
zed --diff src/old_version.rs src/new_version.rs

# Compare two directories
zed --diff ./branch-a/ ./branch-b/

The diff view shows additions, deletions, and modifications side by side.

5.27 Keyboard-Driven Navigation

5.28 Whitespace Visualization

{
  "show_whitespaces": "all"
}

5.29 Custom Font Configuration

{
  "buffer_font_family": "JetBrains Mono",
  "buffer_font_size": 14,
  "buffer_font_weight": 400,
  "buffer_font_features": {
    "liga": true,
    "calt": true
  }
}

Zed supports OpenType font features. Common features include liga (standard ligatures) and calt (contextual alternates).

5.30 Controlling Edit Predictions Per Language

{
  "languages": {
    "Markdown": {
      "show_edit_predictions": false
    },
    "Rust": {
      "show_edit_predictions": true,
      "edit_predictions": {
        "provider": "zed"
      }
    }
  }
}

6. Troubleshooting

6.1 Zed Won't Launch

Symptom: Zed fails to start or immediately crashes.

Possible causes:

• Missing or broken GPU driver (Vulkan/Metal)
• Corrupted settings file

Solutions:

1. Run with foreground logging to see the error:

   zed --foreground
   

2. Check your GPU driver supports Vulkan (Linux):

   vulkaninfo | head -20
   

3. If the settings file is corrupted, reset it:

   # Back up first
   mv ~/.config/zed/settings.json ~/.config/zed/settings.json.bak
   

4. Check system specs for compatibility:

   zed --system-specs
   

6.2 Language Server Not Starting

Symptom: No completions, diagnostics, or go-to-definition for a language.

Solutions:

1. Check the status bar — it shows the language server status for the current file
2. Verify the language extension is installed (Extensions panel)
3. Check that the language server binary is installed and on your $PATH
4. Look at Zed's logs for language server errors (Command Palette: "zed: open log")

Warning

Some language servers (ESLint, Intelephense, and others) may not start if the project is missing configuration files they expect. If you see ESLint or Intelephense not working (#54093), ensure .eslintrc or composer.json exists in your project root.

6.3 Formatting Does Nothing

Symptom: Ctrl+Shift+I or format-on-save produces no changes.

Solutions:

1. Confirm a formatter is configured for the language

2. Check that the language server is running (status bar)

3. Check for language-specific formatter settings:

   {
     "languages": {
       "JavaScript": {
         "format_on_save": "on"
       }
     }
   }
   

4. Some formatters require project-level config (e.g., .prettierrc for Prettier)

6.4 High CPU or Memory Usage

Symptom: Zed consuming excessive resources.

Solutions:

1. Exclude large directories from file scanning:

   {
     "file_scan_exclusions": [
       "node_modules",
       "target",
       ".git",
       "dist",
       "build"
     ]
   }
   

2. Disable features you don't use (edit predictions, inline blame, telemetry)

3. Check for runaway language servers in your system's process monitor

6.5 Terminal Not Using My Shell

Symptom: Terminal opens with the wrong shell or default shell.

Solution:

{
  "terminal": {
    "shell": {
      "program": "/usr/bin/fish"
    }
  }
}

Set shell to the path of your preferred shell, or use "system" to use the OS default.

6.6 Git Gutter Not Showing

Symptom: No added/modified/deleted indicators in the gutter.

Solutions:

1. Ensure the file is inside a Git repository

2. Check the setting:

   {
     "git": {
       "git_gutter": "tracked_files"
     }
   }
   

3. Verify Git is installed and on your $PATH

6.7 Extensions Not Loading

Symptom: Installed extension features don't appear.

Solutions:

1. Restart Zed after installing extensions
2. Check the extension's requirements (some need external tools installed)
3. Open the Zed log (Command Palette: "zed: open log") for extension errors

6.8 Copy/Paste Issues on Linux

Symptom: Shift+Insert pastes from the wrong clipboard.

On Linux with X11, there are two clipboards: CLIPBOARD (Ctrl+C/V) and PRIMARY (mouse selection). There is a known issue (#53446) where Shift+Insert may paste from CLIPBOARD instead of PRIMARY. Use Ctrl+V for CLIPBOARD pasting as a workaround.

Caution

If you rely on PRIMARY selection pasting (middle-click behavior) in the terminal, be aware of the clipboard distinction on Linux. Test both Ctrl+V and Shift+Insert to understand which clipboard each uses in your setup.

6.9 Inlay Hints Not Appearing

Symptom: Inlay hints are enabled but nothing shows.

Solutions:

1. Verify the setting:

   {
     "inlay_hints": {
       "enabled": true
     }
   }
   

2. Confirm the language server supports inlay hints (not all do)

3. Some language servers require separate configuration to enable hints (e.g., rust-analyzer settings)

4. Note: there is a known issue (#54157) with inlay hints in Svelte files

6.10 Keybindings Not Working

Symptom: A keybinding doesn't trigger the expected action.

Solutions:

1. Check for conflicts: open the Command Palette and search for the action to see its current binding
2. Keybinding context matters — some bindings only work in specific views (Editor, Terminal, etc.)
3. If using Vim mode, the binding may be overridden in Normal mode
4. Review your keymap.json for conflicting custom bindings

6.11 Autosave Not Working in Uncommitted Changes View

This is a known issue (#53413). Autosave currently does not apply to files opened in the Uncommitted Changes view. Edit the file directly from the project panel or file finder to ensure autosave works.

6.12 zed --wait Not Blocking

If zed --wait returns immediately instead of waiting for the file to be closed, this is a known issue (#54203) that occurs when Zed is already running. Workarounds:

1. Close other Zed instances before using --wait
2. Use zed -n --wait to open in a new window

6.13 Settings Not Taking Effect

Symptom: Changed a setting but the editor didn't update.

Solutions:

1. Verify JSON syntax — a trailing comma or missing brace invalidates the entire file
2. Check that you edited the correct settings file (global vs. project-local)
3. Language-specific settings in "languages" override top-level settings
4. Project settings (.zed/settings.json) override global settings

6.14 Can't Open Worktree in New Window

Known issue (#54026). "Open worktree in new window" may fail in certain configurations. As a workaround, open the directory directly from the CLI:

zed -n /path/to/worktree

6.15 Files Opening Outside the Project Context

When you open a file that isn't inside the current workspace, Zed may open it in a pseudo-project context (#54095). To avoid this, add the parent directory to your workspace:

zed -a /path/to/parent/directory

6.16 Nested Git Repos Not Opening

Known issue (#53331). Opening a worktree that is inside another Git repository may fail. Work around this by opening the inner repo directly:

zed /path/to/inner/repo

6.17 Theme Not Changing with System Dark/Light Mode

Symptom: System dark/light mode changes but Zed doesn't follow.

Solution:

{
  "theme": {
    "mode": "system"
  }
}

Ensure mode is set to "system", not "dark" or "light".

6.18 Debugger Not Connecting

Symptom: F4 doesn't start debugging or the debugger fails to connect.

Solutions:

1. Verify that the debug adapter for your language is installed
2. Check your .zed/debug.json launch configuration
3. Ensure the binary/program path in the configuration is correct

6.19 Extension-Installed Language Server Failing

Symptom: An extension installed a language server but it shows errors.

Solutions:

1. Check Zed's log (Command Palette: "zed: open log") for the specific error
2. Many language servers require Node.js, Python, or other runtimes installed
3. Some language servers need workspace-level configuration files

Warning

Language server errors are often caused by missing runtime dependencies, not Zed configuration. If a language server requires Node.js 18+ and you have Node.js 16, the extension will install but the server will fail. Check the extension's documentation for requirements.

6.20 Remote Development Connection Failing

Symptom: SSH remote development fails to connect.

Solutions:

1. Verify SSH access works from your terminal: ssh user@hostname
2. Ensure the remote machine allows the Zed server binary to be installed (write access to home directory)
3. Check firewall rules allow the SSH connection
4. Look at Zed's log for detailed connection errors

6.21 Slow File Finder

Symptom: File finder (Ctrl+P) is slow to show results.

Solution: Exclude large directories:

{
  "file_scan_exclusions": [
    "node_modules",
    "target",
    ".git",
    "vendor",
    "build",
    "__pycache__"
  ]
}

6.22 GPU Rendering Issues on Linux

Symptom: Visual glitches, screen tearing, or rendering artifacts.

Solutions:

1. Update your GPU driver to the latest version

2. Try switching between Wayland and X11

3. Check that Vulkan is properly configured:

   vulkaninfo --summary
   

4. Some compositors may cause rendering issues — try disabling compositor effects

6.23 Edit Predictions Not Showing

Symptom: Ghost text predictions never appear.

Solutions:

1. Verify predictions are enabled:

   {
     "show_edit_predictions": true,
     "edit_predictions": {
       "provider": "zed"
     }
   }
   

2. The "zed" provider requires an active internet connection

3. For "copilot", verify your GitHub Copilot subscription is active and authenticated

4. Check that predictions aren't disabled for the current language

6.24 Agent Panel Not Appearing

Symptom: Ctrl+Shift+A doesn't open the Agent.

Solutions:

1. Check that AI is not globally disabled:

   {
     "disable_ai": false,
     "agent": {
       "enabled": true
     }
   }
   

2. Try toggling from the sidebar icons

3. Restart Zed if the panel was recently enabled

6.25 Collaboration Call Issues

Symptom: Can't join a call or share a project.

Solutions:

1. Sign in to Zed (required for collaboration features)
2. Check your internet connection
3. Verify the other party has shared their project
4. Check firewall rules for Zed's collaboration servers

7. FAQ

General

Q: What platforms does Zed support?

Zed runs on macOS (Metal), Linux (Vulkan), and Windows (Vulkan/DirectX 12). All three are actively developed and supported.

Q: Is Zed open source?

Yes. Zed is open source and developed at github.com/zed-industries/zed.

Q: Is Zed free?

Zed is free to download and use. Some cloud features (like the Zed-hosted edit prediction provider and collaboration) may have their own terms.

Q: How do I check my Zed version?

zed --version

Or look in the status bar within the editor.

Q: How do I reset Zed to default settings?

Delete or rename your settings file:

# Linux
mv ~/.config/zed/settings.json ~/.config/zed/settings.json.bak

# macOS
mv ~/Library/Application\ Support/Zed/settings.json ~/Library/Application\ Support/Zed/settings.json.bak

# Windows (PowerShell)
Rename-Item "$env:LOCALAPPDATA\Zed\settings.json" "settings.json.bak"

Q: How do I open Zed's logs?

Use the Command Palette: "zed: open log". Or run Zed with --foreground to see logs in the terminal.

Q: Can I use Zed as my $EDITOR / $VISUAL?

Yes:

export EDITOR="zed --wait"
export VISUAL="zed --wait"

The --wait flag is required so that calling programs (like Git) wait for you to finish editing.

Q: How do I disable telemetry?

{
  "telemetry": {
    "diagnostics": false,
    "metrics": false
  }
}

Q: Where are Zed's configuration files?

Q: Can I use a custom data directory?

Yes:

zed --user-data-dir /custom/path ~/projects/my-app

Q: How do I uninstall Zed?

zed --uninstall

This removes the Zed binary and associated data on Linux and macOS.

Editor

Q: How do I enable line wrapping?

{
  "soft_wrap": "editor_width"
}

Options: "none" (default), "editor_width", "preferred_line_length", "bounded".

Q: How do I change the tab size?

{
  "tab_size": 2
}

Q: How do I use tabs instead of spaces?

{
  "hard_tabs": true
}

Q: How do I enable relative line numbers?

{
  "relative_line_numbers": "enabled"
}

Q: How do I change the cursor style?

{
  "cursor_shape": "block"
}

Options: "bar" (default), "block", "underline", "hollow".

Q: How do I stop the cursor from blinking?

{
  "cursor_blink": false
}

Q: How do I show the minimap?

{
  "minimap": {
    "show": "always"
  }
}

Options: "never" (default), "auto", "always".

Q: How do I enable bracket colorization?

{
  "colorize_brackets": true
}

It is disabled by default.

Q: Can I have per-language settings?

Yes. Nest any editor setting under "languages":

{
  "languages": {
    "Python": {
      "tab_size": 4,
      "format_on_save": "on"
    }
  }
}

Q: How do I change the font?

{
  "buffer_font_family": "Fira Code",
  "buffer_font_size": 14
}

Use any font installed on your system. The default is .ZedMono (which aliases to Lilex).

Keybindings

Q: How do I switch to JetBrains/Sublime/Emacs keybindings?

{
  "base_keymap": "JetBrains"
}

Available keymaps: VSCode (default), Atom, JetBrains, SublimeText, TextMate, Emacs, Cursor, None.

Q: How do I customize individual keybindings?

Open your keymap file (Command Palette: "zed: open keymap") and add bindings:

[
  {
    "context": "Editor",
    "bindings": {
      "ctrl-shift-d": "editor::DuplicateLineDown"
    }
  }
]

Q: What's the multi-cursor key?

Hold Alt (default) and click to place additional cursors. Change it with:

{
  "multi_cursor_modifier": "alt"
}

AI and Edit Predictions

Q: How do I disable all AI features?

{
  "disable_ai": true
}

This turns off the Agent, edit predictions, and all AI-related features.

Q: How do I switch the Agent's default model?

{
  "agent": {
    "default_model": {
      "provider": "zed.dev",
      "model": "claude-sonnet-4"
    }
  }
}

You can also switch models per-conversation using the model picker in the Agent panel.

Q: What's the difference between Agent profiles?

Q: How do I use Copilot for edit predictions instead of Zed's provider?

{
  "edit_predictions": {
    "provider": "copilot"
  }
}

You need an active GitHub Copilot subscription.

Q: Can I use a local model for edit predictions?

Yes, via Ollama:

{
  "edit_predictions": {
    "provider": "ollama"
  }
}

Ensure Ollama is running locally with a code-capable model loaded.

Q: How do I navigate between edit predictions?

Alt+] for next prediction, Alt+[ for previous, Alt+\ to trigger/show a prediction, Tab to accept.

Vim and Modal Editing

Q: How do I enable Vim mode?

{
  "vim_mode": true
}

Q: Can I use Helix-style editing instead of Vim?

{
  "helix_mode": true
}

Helix uses a selection-first model: select text, then act on it.

Q: Are Vim and Helix modes mutually exclusive?

Enable only one at a time. Both modify the same core input handling.

Git

Q: How do I toggle inline blame?

Alt+G B, or configure it permanently:

{
  "git": {
    "inline_blame": {
      "enabled": true
    }
  }
}

Q: How do I hide the git gutter?

{
  "git": {
    "git_gutter": "none"
  }
}

Terminal

Q: How do I change the terminal position?

{
  "terminal": {
    "dock": "right"
  }
}

Options: "bottom" (default), "left", "right".

Q: How do I use a different shell in the terminal?

{
  "terminal": {
    "shell": {
      "program": "/usr/bin/zsh"
    }
  }
}

Extensions

Q: How do I install extensions?

Open the Extensions panel (Command Palette: "zed: extensions"), search for the extension, and click Install. Extensions are WASM-based and run in a sandboxed environment.

Q: What can extensions provide?

Extensions can add: languages, themes, language servers, slash commands (for the Agent), and context servers.

Q: Are extensions safe?

Extensions run in a WASM sandbox, limiting their access to the system. They cannot execute arbitrary system commands or access files outside their sandbox.

Remote Development

Q: How do I edit files on a remote server?

zed ssh://user@hostname/path/to/project

Zed installs a server component on the remote machine and streams the editor UI locally.

Q: How do I use dev containers?

zed --dev-container /path/to/project

The project must have a .devcontainer/devcontainer.json file.

Collaboration

Q: How do I collaborate with someone in real time?

1. Both users need Zed accounts (sign in within the app)
2. One user starts a call via the Collaboration panel
3. The other user joins
4. Share your project from the Collaboration panel
5. Both users can now edit simultaneously with live cursors

Q: Can I auto-share my project when joining a call?

{
  "calls": {
    "share_on_join": true
  }
}

Debugging

Q: How do I start the debugger?

Press F4 to start debugging. Set breakpoints with F9. You need a debug configuration (.zed/debug.json) and the appropriate debug adapter installed.

Q: What debugger keybindings does Zed use?

Startup and Performance

Q: How do I stop Zed from restoring the previous session?

{
  "restore_on_startup": "none"
}

Q: How do I make Zed always open in a new window from the CLI?

{
  "cli_default_open_behavior": "new_window"
}

Or use the -n flag: zed -n /path.

Q: How do I get a quit confirmation dialog?

{
  "confirm_quit": true
}

Disabled by default.

Q: How do I disable auto-update?

{
  "auto_update": false
}