42.17 Batch Mode

The command-line option ‘-batch’ causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with ‘-l file’, which loads the library named file, or ‘-f function’, which calls function with no arguments, or ‘--eval=form’.

Variable: noninteractive ¶

This variable is non-nil when Emacs is running in batch mode.

If the specified Lisp program signals an unhandled error in batch mode, Emacs exits with a non-zero exit status after invoking the Lisp debugger which shows the Lisp backtrace (see Invoking the Debugger) on the standard error stream:

$ emacs -Q --batch --eval '(error "foo")'; echo $?

Error: error ("foo")
mapbacktrace(#f(compiled-function (evald func args flags) #<bytecode -0x4f85c5
7c45e2f81>))
debug-early-backtrace()
debug-early(error (error "foo"))
signal(error ("foo"))
error("foo")
eval((error "foo") t)
command-line-1(("--eval" "(error \"foo\")"))
command-line()
normal-top-level()

foo
255

Any Lisp program output that would normally go to the echo area, either using message, or using prin1, etc., with t as the stream (see Output Streams), goes instead to Emacs’s standard descriptors when in batch mode: message writes to the standard error descriptor, while prin1 and other print functions write to the standard output. Similarly, input that would normally come from the minibuffer is read from the standard input descriptor. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.)

Non-ASCII text written to the standard output or error descriptors is by default encoded using locale-coding-system (see Locales) if it is non-nil; this can be overridden by binding coding-system-for-write to a coding system of you choice (see Explicit Encoding and Decoding).

In batch mode, Emacs will enlarge the value of the gc-cons-percentage variable from the default of ‘0.1’ up to ‘1.0’. Batch jobs that are supposed to run for a long time should adjust the limit back down again, because this means that less garbage collection will be performed by default (and more memory consumed).