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