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