M-! (shell-command) reads a line of text using the minibuffer and executes it as a shell command, in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output appears either in the echo area (if it is short), or in the "*Shell Command Output*" (shell-command-buffer-name) buffer (if the output is long). The variables resize-mini-windows and max-mini-window-height (Minibuffer Edit) control when Emacs should consider the output to be too long for the echo area. For instance, one way to decompress a file named foo.gz is to type M-! gunzip foo.gz RET. That shell command normally creates the file foo and produces no terminal output. A numeric argument to shell-command, e.g., M-1 M-!, causes it to insert terminal output into the current buffer instead of a separate buffer. By default, it puts point before the output, and sets the mark after the output (but a non-default value of shell-command-dont-erase-buffer can change that, see below). For instance, M-1 M-! gunzip < foo.gz RET would insert the uncompressed form of the file foo.gz into the current buffer. Provided the specified shell command does not end with &, it runs synchronously, and you must wait for it to exit before continuing to use Emacs. To stop waiting, type C-g to quit; this sends a SIGINT signal to terminate the shell command (this is the same signal that C-c normally generates in the shell). Emacs then waits until the command actually terminates. If the shell command doesn't stop (because it ignores the SIGINT signal), type C-g again; this sends the command a SIGKILL signal, which is impossible to ignore. A shell command that ends in & is executed asynchronously, and you can continue to use Emacs as it runs. You can also type M-& (async-shell-command) to execute a shell command asynchronously; this is exactly like calling M-! with a trailing &, except that you do not need the &. The output from asynchronous shell commands, by default, goes into the "*Async Shell Command*" buffer (shell-command-buffer-name-async). Emacs inserts the output into this buffer as it comes in, whether or not the buffer is visible in a window. If you want to run more than one asynchronous shell command at the same time, they could end up competing for the output buffer. The option async-shell-command-buffer specifies what to do about this; e.g., whether to rename the pre-existing output buffer, or to use a different buffer for the new command. Consult the variable's documentation for more possibilities. If you want the output buffer for asynchronous shell commands to be displayed only when the command generates output, set async-shell-command-display-buffer to nil. The option async-shell-command-width defines the number of display columns available for output of asynchronous shell commands. A positive integer tells the shell to use that number of columns for command output. The default value is nil that means to use the same number of columns as provided by the shell. To make the above commands show the current directory in their prompts, customize the variable shell-command-prompt-show-cwd to a non-nil value. M-| (shell-command-on-region) is like M-!, but passes the contents of the region as the standard input to the shell command, instead of no input. With a numeric argument, it deletes the old region and replaces it with the output from the shell command. For example, you can use M-| with the gpg program to see what keys are in the buffer. If the buffer contains a GnuPG key, type C-x h M-| gpg RET to feed the entire buffer contents to gpg. This will output the list of keys to the buffer whose name is the value of shell-command-buffer-name. The above commands use the shell specified by the variable shell-file-name. Its default value is determined by the SHELL environment variable when Emacs is started. If the file name is relative, Emacs searches the directories listed in exec-path (Shell). If the default directory is remote (Remote Files), the default value is /bin/sh. This can be changed by declaring shell-file-name connection-local (Connection Variables). To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. Communication Coding. By default, error output is intermixed with the regular output in the output buffer. But if you change the value of the variable shell-command-default-error-buffer to a string, error output is inserted into a buffer of that name. By default, the output buffer is erased between shell commands, except when the output goes to the current buffer. If you change the value of the option shell-command-dont-erase-buffer to erase, then the output buffer is always erased. Other non-nil values prevent erasing of the output buffer, and—if the output buffer is not the current buffer—also control where to put point after inserting the output of the shell command:

beg-last-out

Puts point at the beginning of the last shell-command output.

end-last-out

Puts point at the end of the last shell-command output, i.e. at the end of the output buffer.

save-point

Restores the position of point as it was before inserting the shell-command output.

To run a subshell interactively, type M-x shell. This creates (or reuses) a buffer named *shell*, and runs a shell subprocess with input coming from and output going to that buffer. That is to say, any terminal output from the subshell goes into the buffer, advancing point, and any terminal input for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by RET. By default, when the subshell is invoked interactively, the *shell* buffer is displayed in a new window, unless the current window already shows the *shell* buffer. This behavior can be customized via display-buffer-alist (Window Choice). While the subshell is waiting or running a command, you can switch windows or buffers and perform other editing in Emacs. Emacs inserts the output from the subshell into the Shell buffer whenever it has time to process it (e.g., while waiting for keyboard input). In the Shell buffer, prompts are displayed with the face comint-highlight-prompt, and submitted input lines are displayed with the face comint-highlight-input. This makes it easier to distinguish input lines from the shell output. Faces. To make multiple subshells, invoke M-x shell with a prefix argument (e.g., C-u M-x shell). Then the command will read a buffer name, and create (or reuse) a subshell in that buffer. You can also rename the *shell* buffer using M-x rename-uniquely, then create a new *shell* buffer using plain M-x shell. Subshells in different buffers run independently and in parallel. To specify the shell file name used by M-x shell, customize the variable explicit-shell-file-name. If this is nil (the default), Emacs uses the environment variable ESHELL if it exists. Otherwise, it usually uses the variable shell-file-name (Single Shell); but if the default directory is remote (Remote Files), it prompts you for the shell file name. Minibuffer File, for hints how to type remote file names effectively. Emacs sends the new shell the contents of the file ~/.emacs_shellname as input, if it exists, where shellname is the name of the file that the shell was loaded from. For example, if you use bash, the file sent to it is ~/.emacs_bash. If this file is not found, Emacs tries with ~/.emacs.d/init_shellname.sh. To specify a coding system for the shell, you can use the command C-x RET c immediately before M-x shell. You can also change the coding system for a running subshell by typing C-x RET p in the shell buffer. Communication Coding. Emacs sets the environment variable INSIDE_EMACS in the subshell to /version/, where version is the Emacs version (e.g., 28.1). Programs can check this variable to determine whether they are running inside an Emacs subshell.

The major mode for Shell buffers is Shell mode. Many of its special commands are bound to the C-c prefix, and resemble the usual editing and job control characters present in ordinary shells, except that you must type C-c first. Here is a list of Shell mode commands:

RET

Send the current line as input to the subshell (comint-send-input). Any shell prompt at the beginning of the line is omitted (Shell Prompts). If point is at the end of buffer, this is like submitting the command line in an ordinary interactive shell. However, you can also invoke RET elsewhere in the shell buffer to submit the current line as input.

TAB

Complete the command name or file name before point in the shell buffer (completion-at-point). This uses the usual Emacs completion rules (Completion), with the completion alternatives being file names, environment variable names, the shell command history, and history references (History References). For options controlling the completion, Shell Options.

M-?

Display temporarily a list of the possible completions of the file name before point (comint-dynamic-list-filename-completions).

C-d

Either delete a character or send EOF (comint-delchar-or-maybe-eof). Typed at the end of the shell buffer, this sends EOF to the subshell. Typed at any other position in the buffer, this deletes a character as usual.

C-c C-a

Move to the beginning of the line, but after the prompt if any (comint-bol-or-process-mark). If you repeat this command twice in a row, the second time it moves back to the process mark, which is the beginning of the input that you have not yet sent to the subshell. (Normally that is the same place—the end of the prompt on this line—but after C-c SPC the process mark may be in a previous line.)

C-c SPC

Accumulate multiple lines of input, then send them together (comint-accumulate). This command inserts a newline before point, but does not send the preceding text as input to the subshell—at least, not yet. Both lines, the one before this newline and the one after, will be sent together (along with the newline that separates them), when you type RET.

C-c C-u

Kill all text pending at end of buffer to be sent as input (comint-kill-input). If point is not at end of buffer, this only kills the part of this text that precedes point.

C-c C-w

Kill a word before point (backward-kill-word).

C-c C-c

Interrupt the shell or its current subjob if any (comint-interrupt-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-z

Stop the shell or its current subjob if any (comint-stop-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-\

Send quit signal to the shell or its current subjob if any (comint-quit-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-o

Delete the last batch of output from a shell command (comint-delete-output). This is useful if a shell command spews out lots of output that just gets in the way. With a prefix argument, this command saves the deleted text in the kill-ring (Kill Ring), so that you could later yank it (Yanking) elsewhere.

C-c C-s

Write the last batch of output from a shell command to a file (comint-write-output). With a prefix argument, the file is appended to instead. Any prompt at the end of the output is not written.

C-c C-r, C-M-l

Scroll to display the beginning of the last batch of output at the top of the window; also move the cursor there (comint-show-output).

C-c C-e

Scroll to put the last line of the buffer at the bottom of the window (comint-show-maximum-output).

C-c C-f

Move forward across one shell command, but not beyond the current line (shell-forward-command). The variable shell-command-regexp specifies how to recognize the end of a command.

C-c C-b

Move backward across one shell command, but not beyond the current line (shell-backward-command).

M-x dirs

Ask the shell for its working directory, and update the Shell buffer's default directory. Directory Tracking.

M-x comint-send-invisible RET text RET

Send text as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password. Please note that Emacs will not echo passwords by default. If you really want them to be echoed, evaluate (Lisp Eval) the following Lisp expression: (remove-hook 'comint-output-filter-functions 'comint-watch-for-password-prompt)

M-x comint-continue-subjob

Continue the shell process. This is useful if you accidentally suspend the shell process.(You should not suspend the shell process. Suspending a subjob of the shell is a completely different matter—that is normal practice)

M-x comint-strip-ctrl-m

Discard all control-M characters from the current group of shell output. The most convenient way to use this command is to make it run automatically when you get output from the subshell. To do that, evaluate this Lisp expression: (add-hook 'comint-output-filter-functions 'comint-strip-ctrl-m)

M-x comint-truncate-buffer

This command truncates the shell buffer to a certain maximum number of lines, specified by the variable comint-buffer-maximum-size. Here's how to do this automatically each time you get output from the subshell: (add-hook 'comint-output-filter-functions 'comint-truncate-buffer)

By default, Shell mode handles common ANSI escape codes (for instance, for changing the color of text). Emacs also optionally supports some extend escape codes, like some of the OSC (Operating System Codes) if you put the following in your init file:

(add-hook 'comint-output-filter-functions 'comint-osc-process-output)

With this enabled, the output from, for instance, ls --hyperlink will be made into clickable buttons in the Shell mode buffer. Shell mode is a derivative of Comint mode, a general-purpose mode for communicating with interactive subprocesses. Most of the features of Shell mode actually come from Comint mode, as you can see from the command names listed above. The special features of Shell mode include the directory tracking feature, and a few user commands. Other Emacs features that use variants of Comint mode include GUD (Debuggers) and M-x run-lisp (External Lisp). You can use M-x comint-run to execute any program of your choice in a subprocess using unmodified Comint mode—without the specializations of Shell mode. To pass arguments to the program, use C-u M-x comint-run.

A prompt is text output by a program to show that it is ready to accept new user input. Normally, Comint mode (and thus Shell mode) automatically figures out which part of the buffer is a prompt, based on the output of the subprocess. (Specifically, it assumes that any received output line which doesn't end with a newline is a prompt.) Comint mode divides the buffer into two types of fields: input fields (where user input is typed) and output fields (everywhere else). Prompts are part of the output fields. Most Emacs motion commands do not cross field boundaries, unless they move over multiple lines. For instance, when point is in the input field on a shell command line, C-a puts point at the beginning of the input field, after the prompt. Internally, the fields are implemented using the field text property (Text Properties). If you change the variable comint-use-prompt-regexp to a non-nil value, then Comint mode will recognize prompts using a regular expression (Regexps). In Shell mode, the regular expression is specified by the variable shell-prompt-pattern. The default value of comint-use-prompt-regexp is nil, because this method for recognizing prompts is unreliable, but you may want to set it to a non-nil value in unusual circumstances. In that case, Emacs does not divide the Comint buffer into fields, so the general motion commands behave as they normally do in buffers without special text properties. However, you can use the paragraph motion commands to conveniently navigate the buffer (Paragraphs); in Shell mode, Emacs uses shell-prompt-pattern as paragraph boundaries.

Shell buffers support three ways of repeating earlier commands. You can use keys like those used for the minibuffer history; these work much as they do in the minibuffer, inserting text from prior commands while point remains always at the end of the buffer. You can move through the buffer to previous inputs in their original place, then resubmit them or copy them to the end. Or you can use a !-style history reference.

Shell mode keeps track of cd, pushd and popd commands given to the subshell, in order to keep the Shell buffer's default directory (File Names) the same as the shell's working directory. It recognizes these commands by examining lines of input that you send. If you use aliases for these commands, you can tell Emacs to recognize them also, by setting the variables shell-pushd-regexp, shell-popd-regexp, and shell-cd-regexp to the appropriate regular expressions (Regexps). For example, if shell-pushd-regexp matches the beginning of a shell command line, that line is regarded as a pushd command. These commands are recognized only at the beginning of a shell command line. If Emacs gets confused about changes in the working directory of the subshell, type M-x dirs. This command asks the shell for its working directory and updates the default directory accordingly. It works for shells that support the most common command syntax, but may not work for unusual shells. You can also use Dirtrack mode, a buffer-local minor mode that implements an alternative method of tracking the shell's working directory. To use this method, your shell prompt must contain the working directory at all times, and you must supply a regular expression for recognizing which part of the prompt contains the working directory; see the documentation of the variable dirtrack-list for details. To use Dirtrack mode, type M-x dirtrack-mode in the Shell buffer, or add dirtrack-mode to shell-mode-hook (Hooks).

If the variable comint-scroll-to-bottom-on-input is non-nil, insertion and yank commands scroll the selected window to the bottom before inserting. The default is nil. If comint-scroll-show-maximum-output is non-nil, then arrival of output when point is at the end tries to scroll the last line of text to the bottom line of the window, showing as much useful text as possible. (This mimics the scrolling behavior of most terminals.) The default is t. By setting comint-move-point-for-output, you can opt for having point jump to the end of the buffer whenever output arrives—no matter where in the buffer point was before. If the value is this, point jumps in the selected window. If the value is all, point jumps in each window that shows the Comint buffer. If the value is other, point jumps in all nonselected windows that show the current buffer. The default value is nil, which means point does not jump to the end. If you set comint-prompt-read-only, the prompts in the Comint buffer are read-only. The variable comint-input-ignoredups controls whether successive identical inputs are stored in the input history. A non-nil value means to omit an input that is the same as the previous input. The default is nil, which means to store each input even if it is equal to the previous input. Three variables customize file name completion. The variable comint-completion-addsuffix controls whether completion inserts a space or a slash to indicate a fully completed file or directory name (non-nil means do insert a space or slash). comint-completion-recexact, if non-nil, directs TAB to choose the shortest possible completion if the usual Emacs completion algorithm cannot add even a single character. comint-completion-autolist, if non-nil, says to list all the possible completions whenever completion is not exact. Command completion normally considers only executable files. If you set shell-completion-execonly to nil, it considers nonexecutable files as well. The variable shell-completion-fignore specifies a list of file name extensions to ignore in Shell mode completion. The default setting is nil, but some users prefer ("~" "#" "%") to ignore file names ending in ~, # or %. Other related Comint modes use the variable comint-completion-fignore instead. Some implementation details of the shell command completion may also be found in the lisp documentation of the shell-dynamic-complete-command function. You can configure the behavior of pushd. Variables control whether pushd behaves like cd if no argument is given (shell-pushd-tohome), pop rather than rotate with a numeric argument (shell-pushd-dextract), and only add directories to the directory stack if they are not already on it (shell-pushd-dunique). The values you choose should match the underlying shell, of course. Comint mode sets the TERM environment variable to a safe default value, but this value disables some useful features. For example, color is disabled in applications that use TERM to determine if color is supported. Therefore, Emacs provides an option comint-terminfo-terminal, which you can set to a terminal that is present in your system's terminfo database, in order to take advantage of advanced features of that terminal.

To run a subshell in a text terminal emulator, use M-x term. This creates (or reuses) a buffer named *terminal*, and runs a subshell with input coming from your keyboard, and output going to that buffer. The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode (Shell Mode). In char mode, each character is sent directly to the subshell, as terminal input; the sole exception is the terminal escape character, which by default is C-c (Term Mode). Any echoing of your input is the responsibility of the subshell; any terminal output from the subshell goes into the buffer, advancing point. Some programs (such as Emacs itself) need to control the appearance of the terminal screen in detail. They do this by emitting special control codes. Term mode recognizes and handles ANSI-standard VT100-style escape sequences, which are accepted by most modern terminals, including xterm. (Hence, you can actually run Emacs inside an Emacs Term window.) The term face specifies the default appearance of text in the terminal emulator (the default is the same appearance as the default face). When terminal control codes are used to change the appearance of text, these are represented in the terminal emulator by the faces term-color-black, term-color-red, term-color-green, term-color-yellow term-color-blue, term-color-magenta, term-color-cyan, term-color-white, term-color-underline, and term-color-bold. Faces. You can also use Term mode to communicate with a device connected to a serial port. Serial Terminal. The file name used to load the subshell is determined the same way as for Shell mode. To make multiple terminal emulators, rename the buffer *terminal* to something different using M-x rename-uniquely, just as with Shell mode. Unlike Shell mode, Term mode does not track the current directory by examining your input. But some shells can tell Term what the current directory is. This is done automatically by bash version 1.15 and later.

To switch between line and char mode in Term mode, use these commands:

C-c C-j

Switch to line mode (term-line-mode). Do nothing if already in line mode.

C-c C-k

Switch to char mode (term-char-mode). Do nothing if already in char mode.

The following commands are only available in char mode:

C-c C-c

Send a literal C-c to the sub-shell (term-interrupt-subjob).

C-c char

This is equivalent to C-x char in normal Emacs. For example, C-c o invokes the global binding of C-x o, which is normally other-window.

Term mode has a page-at-a-time feature. When enabled, it makes output pause at the end of each screenful:

C-c C-q

Toggle the page-at-a-time feature (term-pager-toggle). This command works in both line and char modes. When the feature is enabled, the mode-line displays the word page, and each time Term receives more than a screenful of output, it pauses and displays **MORE** in the mode-line. Type SPC to display the next screenful of output, or ? to see your other options. The interface is similar to the more program.

You can login to a remote computer, using whatever commands you would from a regular terminal (e.g., using the ssh or telnet or rlogin commands), from a Term window. A program that asks you for a password will normally suppress echoing of the password, so the password will not show up in the buffer. This will happen just as if you were using a real terminal, if the buffer is in char mode. If it is in line mode, the password is temporarily visible, but will be erased when you hit return. (This happens automatically; there is no special password processing.) When you log in to a different machine, you need to specify the type of terminal you're using, by setting the TERM environment variable in the environment for the remote login command. (If you use bash, you do that by writing the variable assignment before the remote login command, without a separating comma.) Terminal types ansi or vt100 will work on most systems.

If you have a device connected to a serial port of your computer, you can communicate with it by typing M-x serial-term. This command asks for a serial port name and speed, and switches to a new Term mode buffer. Emacs communicates with the serial device through this buffer just like it does with a terminal in ordinary Term mode. The speed of the serial port is measured in bits per second. The most common speed is 9600 bits per second. You can change the speed interactively by clicking on the mode line. A serial port can be configured even more by clicking on 8N1 in the mode line. By default, a serial port is configured as 8N1, which means that each byte consists of 8 data bits, No parity check bit, and 1 stopbit. If the speed or the configuration is wrong, you cannot communicate with your device and will probably only see garbage output in the window.