Wolfram Language Scripts

Script Files

A Wolfram Language script is simply a file containing Wolfram Language commands that you would normally evaluate sequentially in a Wolfram Language session. Writing a script is useful if the commands need to be repeated many times. Collecting these commands together ensures that they are evaluated in a particular sequence with no command omitted. This is important if you run complex and long calculations.

When you use the Wolfram Language interactively, the commands contained in the script file can be evaluated using (RefLink[Get, paclet:ref/Get]). This function can also be used programmatically in your code or other .wl files.

Reading commands from a script file.

There is no requirement concerning the structure of the script file. Any sequence of Wolfram Language commands given in the file will be read and evaluated sequentially. If your code is more complex than a plain list of commands, you may want to consider writing a more structured package, as described in "Setting Up Wolfram Language Packages".

The Wolfram Language script is more useful when there is no need for an interactive session; that is, when your script encapsulates a single calculation that needs to be performed—for example, if your calculation involves heavy computational tasks, such as linear algebra, optimization, numerical integration, or solution of differential equations, and when you do not use typesetting, dynamic interactivity, or notebooks.

Scripts may be stored either in normal .wl package files or in dedicated .wls script files. The contents of both files are the same: a series of Wolfram Language expressions, with an optional "shebang" line at the start for use on Unix-like operating systems (see Unix Script Executables). The only difference between the file types is their double-click behavior. Double-clicking a package file will open the file in the notebook package editor, while double-clicking a script file will execute it when supported by the operating system. This is particularly advantageous on Windows, where it is not possible to associate a program with a particular file, only a file extension. A script file can be edited in the notebook interface but must be opened using File ▶ Open.

Running the Script in a Local Kernel

The script file can be used when invoking the Wolfram Language kernel from the command line, using the following typical locations for the kernel executable.

$ "%ProgramFiles%\Wolfram Research\Mathematica\$VersionNumber\wolfram" -script file.wl

Running the script file on Windows.

$ /Applications/Mathematica.app/Contents/MacOS/wolfram -script file.wl

Running the script file on Mac.

$ wolfram -script file.wl

Running the script on Linux.

The (RefLink[-script, paclet:ref/program/WolframKernel]) command line option specifies that the Wolfram Language kernel is to be run in a special script, or batch, mode. In this mode, the kernel reads the specified file and sequentially evaluates its commands. The kernel turns off the default linewrapping by setting the (RefLink[PageWidth, paclet:ref/PageWidth]) option of the output functions to (RefLink[Infinity, paclet:ref/Infinity]) and prints no (RefLink[In, paclet:ref/In])[] and (RefLink[Out, paclet:ref/Out])[] labels. When run in this mode, the standard input and output channels stdin, stdout, and stderr are not redirected, and numbers are formatted in (RefLink[InputForm, paclet:ref/InputForm]).

Running wolfram with the (RefLink[-script, paclet:ref/program/WolframKernel]) option is equivalent to reading the file using the (RefLink[Get, paclet:ref/Get]) command, with a single difference: after the last command in the file is evaluated, the kernel terminates. This behavior may have an effect on the Wolfram Symbolic Transfer Protocol (WSTP) connections or external processes that were created by running the script.

Running the Script Using WolframScript

Scripts can also be run using the (RefLink[WolframScript, paclet:ref/program/wolframscript]) interpreter as follows. The -file flag is optional.

$ wolframscript -file file.wl

Running the script using WolframScript.

(RefLink[WolframScript, paclet:ref/program/wolframscript]) will find the best local kernel it can to run the script. If it fails to find any local kernels, it will connect to the cloud and run the script there. The program accepts various flags in order to control which local or cloud kernel is used for evaluation. It also sets Script Parameters, which allow the script to change its behavior based on how it was launched or what input in receives. Another advantage of using (RefLink[WolframScript, paclet:ref/program/wolframscript]) is that input and output are fully buffered, allowing various transforms to be applied to them. All of these additional options are described along with examples on the (RefLink[WolframScript, paclet:ref/program/wolframscript]) page.

On Windows and Linux, (RefLink[WolframScript, paclet:ref/program/wolframscript]) is typically installed along with the Wolfram System. On Mac, it is necessary to run the "Extras" installer bundled with the Wolfram System in order to obtain (RefLink[WolframScript, paclet:ref/program/wolframscript]). These installers will place wolframscript on the PATH by default.

Unix Script Executables

Unix-like operating systems—as well as Unix environments for Windows such as cygwin and MinGW—allow writing scripts that can be made executable and run as regular executable programs. This is done by putting an "interpreter" line at the beginning of the file. The same can be done with the script containing Wolfram Language commands.

The "interpreter" line consists of two characters, #!, which must be the first two characters in the file, followed by the absolute path to an executable, followed by other arguments. For maximum compatibility across platforms and machines, it is recommended that (RefLink[WolframScript, paclet:ref/program/wolframscript]) be launched via the helper /usr/bin/env as shown below. The env program will find wolframscript on the PATH and then launch it correctly.

#!/usr/bin/env wolframscript

(* generate high-precision samples of a mixed distribution *)
Print /@ RandomVariate[MixtureDistribution[
    {1,2},
    {NormalDistribution[1,2/10],
     NormalDistribution[3,1/10]}],
    10,  WorkingPrecision -> 50]

Example of a script file.

To make the script executable, you need to set executable permissions. After that, the script can be run simply by typing its name at a shell prompt.

$ chmod a+x script.wls
$ ./script.wls

Make the script executable and run it.

The interpreter line may additionally contain other parameters for the interpreter. Possible parameters are specified on the (RefLink[WolframScript, paclet:ref/program/wolframscript]) page.

#!/usr/bin/env wolframscript -linewise -format XML

Interpreter line using additional parameters.

The Wolfram Language script does not need to have the .wl or .wls extensions. An executable script is a full-featured program equivalent to any other program in a Unix operating system, so it can be used in other scripts, in pipes, subject to job control, etc. Each Wolfram Language script launches its own copy of the (RefLink[WolframKernel, paclet:ref/program/WolframKernel]), which does not share variables or definitions. Note that running Wolfram Language scripts concurrently may be affected by the licensing restriction on how many kernels you may run simultaneously.

Executable script files can be transparently read and evaluated in an interactive Wolfram Language session. The (RefLink[Get, paclet:ref/Get]) command will normally ignore the first line of the script if it starts with the #! characters.

It is possible to avoid the use of the env program, but then the path to wolframscript must be an absolute path. The operating system mechanism used to launch the script does not use PATH or other means to find the file. Moreover, the path to the interpreter may not contain spaces.

Scripts on Windows

Standalone scripts can also be used on Windows. Unlike Unix-like operating systems, these scripts must have the extension .wls to be recognized as Wolfram Language scripts. They can be launched from Windows Explorer by double-clicking them, and from Command Prompt by simply typing in their name. The Unix interpreter line, if present, is ignored by this mechanism.

> file.wls

Launching a script from the command prompt, equivalent to the double-click action.

In Command Prompt, additional arguments can be passed after the file name. These arguments are not seen by (RefLink[WolframScript, paclet:ref/program/wolframscript]) itself, but are instead passed to the script as parameters, as explained in the next section.

> file.wls arg1 arg2

Launching a script from the command prompt with two additional arguments.

Script Parameters

When running a Wolfram Language script, you may often want to modify the behavior of the script by specifying parameters on the command line. It is possible for the Wolfram Language code to access parameters passed to the Wolfram Language script via (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine]). Additionally, the contents of standard input are available to be processed as a string in the variable (RefLink[$ScriptInputString, paclet:ref/$ScriptInputString]).

Variables that give information about how the script is run.

#!/usr/bin/env wolframscript

(* generate "num" samples of a mixed distribution *) 
num  = ToExpression[$ScriptCommandLine[[2]]];
Print /@ RandomVariate[
  MixtureDistribution[ 
    {1, 2},
    {NormalDistribution[1, 0.2],
     NormalDistribution[3, 0.1]}
  ], num,  WorkingPrecision -> 50]

Example of a script file, file.wls, using a command-line parameter.

$ ./file.wls 10

Run the script and specify the number of samples in a Unix environment.

> file.wls 10

Run the script and specify the number of samples on Windows.

When accessed in the script, the (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine]) is a list containing the name of the script as the first element and the rest of the command line arguments. (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine]) follows the standard argv[] convention. Notice that this completely hides the path to the interpreter or any arguments passed to it on the #! line.

Due to the way the Unix-like operating systems execute scripts, the (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine]) is set to a non-empty list only if the Wolfram Language kernel is invoked via (RefLink[wolframscript, paclet:ref/program/wolframscript]). If the script is intended to be run both in a batch mode and as a standalone Unix script, the current execution mode can be determined by evaluating (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine])==={}. Then, either (RefLink[$ScriptCommandLine, paclet:ref/$ScriptCommandLine]) or (RefLink[$CommandLine, paclet:ref/$CommandLine]) should be used to access the command-line arguments.