1# Terminal
  2
  3Zed includes a built-in terminal emulator that supports multiple terminal instances, custom shells, and deep integration with the editor.
  4
  5## Opening Terminals
  6
  7| Action                  | macOS           | Linux/Windows   |
  8| ----------------------- | --------------- | --------------- |
  9| Toggle terminal panel   | `` Ctrl+` ``    | `` Ctrl+` ``    |
 10| Open new terminal       | `Ctrl+~`        | `Ctrl+~`        |
 11| Open terminal in center | Command palette | Command palette |
 12
 13You can also open a terminal from the command palette with `terminal panel: toggle` or `workspace: new terminal`.
 14
 15### Terminal Panel vs Center Terminal
 16
 17Terminals can open in two locations:
 18
 19- **Terminal Panel** — Docked at the bottom (default), left, or right of the workspace. Toggle with `` Ctrl+` ``.
 20- **Center Pane** — Opens as a regular tab alongside your files. Use `workspace: new center terminal` from the command palette.
 21
 22## Working with Multiple Terminals
 23
 24Create additional terminals with `Cmd+N` (macOS) or `Ctrl+N` (Linux/Windows) while focused in the terminal panel. Each terminal appears as a tab in the panel.
 25
 26Split terminals horizontally with `Cmd+D` (macOS) or `Ctrl+Shift+5` (Linux/Windows).
 27
 28## Configuring the Shell
 29
 30By default, Zed uses your system's default shell (from `/etc/passwd` on Unix systems). To use a different shell:
 31
 32```json [settings]
 33{
 34  "terminal": {
 35    "shell": {
 36      "program": "/bin/zsh"
 37    }
 38  }
 39}
 40```
 41
 42To pass arguments to your shell:
 43
 44```json [settings]
 45{
 46  "terminal": {
 47    "shell": {
 48      "with_arguments": {
 49        "program": "/bin/bash",
 50        "args": ["--login"]
 51      }
 52    }
 53  }
 54}
 55```
 56
 57## Working Directory
 58
 59Control where new terminals start:
 60
 61| Value                                         | Behavior                                                        |
 62| --------------------------------------------- | --------------------------------------------------------------- |
 63| `"current_project_directory"`                 | Uses the project directory of the currently open file (default) |
 64| `"first_project_directory"`                   | Uses the first project in your workspace                        |
 65| `"always_home"`                               | Always starts in your home directory                            |
 66| `{ "always": { "directory": "~/projects" } }` | Always starts in a specific directory                           |
 67
 68```json [settings]
 69{
 70  "terminal": {
 71    "working_directory": "first_project_directory"
 72  }
 73}
 74```
 75
 76## Environment Variables
 77
 78Add environment variables to all terminal sessions:
 79
 80```json [settings]
 81{
 82  "terminal": {
 83    "env": {
 84      "EDITOR": "zed --wait",
 85      "MY_VAR": "value"
 86    }
 87  }
 88}
 89```
 90
 91> **Tip:** Use `:` to separate multiple values in a single variable: `"PATH": "/custom/path:$PATH"`
 92
 93### Python Virtual Environment Detection
 94
 95Zed can automatically activate Python virtual environments when opening a terminal. By default, it searches for `.env`, `env`, `.venv`, and `venv` directories:
 96
 97```json [settings]
 98{
 99  "terminal": {
100    "detect_venv": {
101      "on": {
102        "directories": [".venv", "venv"],
103        "activate_script": "default"
104      }
105    }
106  }
107}
108```
109
110The `activate_script` option supports `"default"`, `"csh"`, `"fish"`, and `"nushell"`.
111
112To disable virtual environment detection:
113
114```json [settings]
115{
116  "terminal": {
117    "detect_venv": "off"
118  }
119}
120```
121
122## Fonts and Appearance
123
124The terminal can use different fonts from the editor:
125
126```json [settings]
127{
128  "terminal": {
129    "font_family": "JetBrains Mono",
130    "font_size": 14,
131    "font_features": {
132      "calt": false
133    },
134    "line_height": "comfortable"
135  }
136}
137```
138
139Line height options:
140
141- `"comfortable"` — 1.618 ratio, good for reading (default)
142- `"standard"` — 1.3 ratio, better for TUI applications with box-drawing characters
143- `{ "custom": 1.5 }` — Custom ratio
144
145### Cursor
146
147Configure cursor appearance:
148
149```json [settings]
150{
151  "terminal": {
152    "cursor_shape": "bar",
153    "blinking": "on"
154  }
155}
156```
157
158Cursor shapes: `"block"`, `"bar"`, `"underline"`, `"hollow"`
159
160Blinking options: `"off"`, `"terminal_controlled"` (default), `"on"`
161
162### Minimum Contrast
163
164Zed adjusts terminal colors to maintain readability. The default value of `45` ensures text remains visible. Set to `0` to disable contrast adjustment and use exact theme colors:
165
166```json [settings]
167{
168  "terminal": {
169    "minimum_contrast": 0
170  }
171}
172```
173
174## Scrolling
175
176Navigate terminal history with these keybindings:
177
178| Action           | macOS                          | Linux/Windows    |
179| ---------------- | ------------------------------ | ---------------- |
180| Scroll page up   | `Shift+PageUp` or `Cmd+Up`     | `Shift+PageUp`   |
181| Scroll page down | `Shift+PageDown` or `Cmd+Down` | `Shift+PageDown` |
182| Scroll line up   | `Shift+Up`                     | `Shift+Up`       |
183| Scroll line down | `Shift+Down`                   | `Shift+Down`     |
184| Scroll to top    | `Shift+Home` or `Cmd+Home`     | `Shift+Home`     |
185| Scroll to bottom | `Shift+End` or `Cmd+End`       | `Shift+End`      |
186
187Adjust scroll speed with:
188
189```json [settings]
190{
191  "terminal": {
192    "scroll_multiplier": 3.0
193  }
194}
195```
196
197## Copy and Paste
198
199| Action | macOS   | Linux/Windows  |
200| ------ | ------- | -------------- |
201| Copy   | `Cmd+C` | `Ctrl+Shift+C` |
202| Paste  | `Cmd+V` | `Ctrl+Shift+V` |
203
204### Copy on Select
205
206Automatically copy selected text to the clipboard:
207
208```json [settings]
209{
210  "terminal": {
211    "copy_on_select": true
212  }
213}
214```
215
216### Keep Selection After Copy
217
218By default, text stays selected after copying. To clear the selection:
219
220```json [settings]
221{
222  "terminal": {
223    "keep_selection_on_copy": false
224  }
225}
226```
227
228## Search
229
230Search terminal content with `Cmd+F` (macOS) or `Ctrl+Shift+F` (Linux/Windows). This opens the same search bar used in the editor.
231
232## Vi Mode
233
234Toggle vi-style navigation in the terminal with `Ctrl+Shift+Space`. This allows you to navigate and select text using vi keybindings.
235
236## Clear Terminal
237
238Clear the terminal screen:
239
240- macOS: `Cmd+K`
241- Linux/Windows: `Ctrl+Shift+L`
242
243## Option as Meta (macOS)
244
245For Emacs users or applications that use Meta key combinations, enable Option as Meta:
246
247```json [settings]
248{
249  "terminal": {
250    "option_as_meta": true
251  }
252}
253```
254
255This reinterprets the Option key as Meta, allowing sequences like `Alt+X` to work correctly.
256
257## Alternate Scroll Mode
258
259When enabled, mouse scroll events are converted to arrow key presses in applications like `vim` or `less`:
260
261```json [settings]
262{
263  "terminal": {
264    "alternate_scroll": "on"
265  }
266}
267```
268
269## Path Hyperlinks
270
271Zed detects file paths in terminal output and makes them clickable. `Cmd+Click` (macOS) or `Ctrl+Click` (Linux/Windows) opens the file in Zed, jumping to the line number if one is detected.
272
273Common formats recognized:
274
275- `src/main.rs:42` — Opens at line 42
276- `src/main.rs:42:10` — Opens at line 42, column 10
277- `File "script.py", line 10` — Python tracebacks
278
279## Panel Configuration
280
281### Dock Position
282
283```json [settings]
284{
285  "terminal": {
286    "dock": "bottom"
287  }
288}
289```
290
291Options: `"bottom"` (default), `"left"`, `"right"`
292
293### Default Size
294
295```json [settings]
296{
297  "terminal": {
298    "default_width": 640,
299    "default_height": 320
300  }
301}
302```
303
304### Terminal Button
305
306Hide the terminal button in the status bar:
307
308```json [settings]
309{
310  "terminal": {
311    "button": false
312  }
313}
314```
315
316### Toolbar
317
318Show the terminal title in a breadcrumb toolbar:
319
320```json [settings]
321{
322  "terminal": {
323    "toolbar": {
324      "breadcrumbs": true
325    }
326  }
327}
328```
329
330The title can be set by your shell using the escape sequence `\e]2;Title\007`.
331
332## Integration with Tasks
333
334The terminal integrates with Zed's [task system](./tasks.md). When you run a task, it executes in the terminal. Rerun the last task from a terminal with:
335
336- macOS: `Cmd+Alt+R`
337- Linux/Windows: `Ctrl+Shift+R` or `Alt+T`
338
339## AI Assistance
340
341Get help with terminal commands using inline assist:
342
343- macOS: `Ctrl+Enter`
344- Linux/Windows: `Ctrl+Enter` or `Ctrl+I`
345
346This opens the AI assistant to help explain errors, suggest commands, or troubleshoot issues.
347
348## Sending Text and Keystrokes
349
350For advanced keybinding customization, you can send raw text or keystrokes to the terminal:
351
352```json [keymap]
353{
354  "context": "Terminal",
355  "bindings": {
356    "alt-left": ["terminal::SendText", "\u001bb"],
357    "ctrl-c": ["terminal::SendKeystroke", "ctrl-c"]
358  }
359}
360```
361
362## All Terminal Settings
363
364For the complete list of terminal settings, see the [Terminal section in All Settings](./reference/all-settings.md#terminal).
365
366## What's Next
367
368- [Tasks](./tasks.md) — Run commands and scripts from Zed
369- [REPL](./repl.md) — Interactive code execution
370- [CLI Reference](./reference/cli.md) — Command-line interface for opening files in Zed