"Shell" (External Evaluation System)
ExternalEvaluate Usage

- ExternalEvaluate["Shell",code] executes a string in an operating system shell and returns the result as a Wolfram Language expression.
- ExternalEvaluate["Shell"form,code] executes the command string and returns the result in the specified form. Possible specifications for form are "Expression", "StandardOutput", "StandardError", "ExitCode" and "Association".
Examples
open allclose allBasic Examples (2)Summary of the most common use cases
Run a command in your default shell and return the result:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-pcce2y

If a command "ExitCode" is not 0, a Failure object is returned:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-o81rq

Type > to get a Shell code cell that uses ExternalEvaluate to evaluate:

Use the File wrapper to execute code contained in a file:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-e2tkx0

On Unix systems, make sure the file is executable:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-s251z6


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-oumm2b

Deploy code using CloudDeploy and then run the code directly from a CloudObject:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-qsnyet


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-6zggba

Use a URL wrapper to directly run code hosted online:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-o24t34

Scope (20)Survey of the scope of standard use cases

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-kxui9e

Evaluate a command and return the result:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-detsey

Extract the "ExitCode" from the result:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-fxthr2

Extract the original command from the result:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-86j50m

Extract the "StandardOutput" and "StandardError" from the result:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-e3tmu


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-dwl4lu
Use "ReturnType" to specify a different return type:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-bqup95


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-szm839


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-uztfou

Session Options (10)
"ReturnType" (3)
For Shell systems, the default return type is "Expression":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-wtbdnk

With the return type of "Expression", the result will be a Success or a Failure depending on the exit code:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-0nsgec

You can extract additional information about the program's output using the properties "StandardOutput", "StandardError" and "ExitCode":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-35687l


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-jclr5x

Possible values for "ReturnType" are "Expression", "StandardOutput", "StandardError" and "ExitCode":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-5qg8yf


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-7plv6t


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-3499b3


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-ci46n1

You can use a Rule to quickly specify the "ReturnType":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-lpue9q

“Evaluator" (2)
Evaluate code using a specified "Evaluator":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-wrsily

On Windows, use the following to run a command using cmd.exe:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-t5kepm

To run commands on Windows PowerShell, use the following:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-ovu45d

"SessionProlog" (2)
"SessionEpilog" (1)
"Prolog" (1)
Command Options (8)
"Command" (5)
When a string is provided, the command is directly executed:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-c6bi9t

The above is equivalent to writing the command using this form:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-17i6vu

Create a file with a script in it:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-dnm902

Un Unix systems, make sure the file is executable:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-7u1au

Use a File wrapper to run the code from the file:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-cti8jb

The above is equivalent to writing the command using this form:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-p8tnl5


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-g13atf

Use a URL wrapper to directly run code hosted online:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-17j67r

The above is equivalent to writing the command using this form:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-u52xs5

Put code in a CloudObject:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-hee6of

Evaluate directly from the cloud:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-9m0s4q

The above is equivalent to writing the command using this form:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-i5g92o

"ReturnType" (1)
"TemplateArguments" (2)
When running a command, you can inline a TemplateExpression:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-fjfgam


You can explicitly fill TemplateSlot using "TemplateArguments":

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-2px1xh

If you need more than one argument, you can use a List:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-ffga8d

You can name template slots and use an Association to pass named arguments to the template:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-5n2k7d

Applications (3)Sample problems that can be solved with this function
Get your local network address:

Use Spotlight to search for specific files on your Mac:

Show the 10 largest open files:

Create a function to make sure that a local Git repository is up to date:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-fcfgcl

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-rdrgu2

Use Shell to automate the download of a Git repository, build the program from source and run the program:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-wf7yzh

Properties & Relations (2)Properties of the function, and connections to other functions
Use FindExternalEvaluators to find all available Evaluators in your machine:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-krul1s

Use "Evaluator" to manually specify a shell on your machine:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-7dqb0n

Powershell.exe is a valid "Evaluator" on a Windows system:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-qrr136


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-djfap5

RunProcess can also be used to execute shell commands, but it does not print output interactively:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-ng61ld


https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-btfza4

Possible Issues (2)Common pitfalls and unexpected behavior
ExternalEvaluate is unable to interrupt if the program is asking for input:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-gzc571

When running external commands that are requiring user input, it is advised to run them in a non-interactive mode:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-2p031e

ExternalEvaluate is printing output in real time:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-nf80th
$Output can be used to suppress Print output:

https://wolfram.com/xid/0gxr4tewogh7cm3zt00mrihebzse1-4s1fjm
