Files, Streams, and External Operations

Reading and Writing Wolfram System Files

Storing Wolfram Language Expressions in External Files

You can use files on your computer system to store definitions and results from the Wolfram Language. The most general approach is to store everything as plain text that is appropriate for input to the Wolfram Language. With this approach, a version of the Wolfram Language running on one computer system produces files that can be read by a version running on any computer system. In addition, such files can be manipulated by other standard programs, such as text editors.
<<file or Get["file"]
read in a file of Wolfram Language input, and return the last expression in the file
display the contents of a file
expr>>file or Put[expr,"file"]
write an expression to a file
expr>>>file or PutAppend[expr,"file"]
append an expression to a file
Reading and writing files.
This expands and outputs the result to a file called tmp:
Here are the contents of tmp. They can be used directly as input for the Wolfram Language:
This reads in tmp, evaluating the Wolfram Language input it contains:
This shows the contents of the file factors:
This reads in the file and returns the last expression in it:
If the Wolfram Language cannot find the file you ask it to read, it prints a message, then returns the symbol $Failed:
When you read in a file with <<file, the Wolfram Language returns the last expression it evaluates in the file. You can avoid getting any visible result from reading a file by ending the last expression in the file with a semicolon, or by explicitly adding Null after that expression.
If the Wolfram Language encounters a syntax error while reading a file, it reports the error, skips the remainder of the file, then returns $Failed. If the syntax error occurs in the middle of a package that uses BeginPackage and other context manipulation functions, then the Wolfram Language tries to restore the context to what it was before the package was read.

Saving Multiple Wolfram Language Expressions

The Wolfram Language input files can contain any number of expressions. Each expression, however, must start on a new line. The expressions may continue for as many lines as necessary. Just as in a standard interactive Wolfram Language session, the expressions are processed as soon as they are complete. Note that in a file, unlike an interactive session, you can insert a blank line at any point without effect.
When you use expr>>>file, the Wolfram Language appends each new expression you give to the end of your file. If you use expr>>file, however, then the Wolfram Language instead wipes out anything that was in the file before, and then puts expr into the file.
This writes an expression to the file tmp:
Here are the contents of the file:
This appends another expression to the same file:
Both expressions are now in the file:
If you are familiar with commandline operating systems, you will recognize the Wolfram Language redirection operators >>, >>>, and << as being analogous to the commandline operators >, >>, and <.

Saving Wolfram Language Expressions in Different Formats

When you use either >> or >>> to write expressions to files, the expressions are usually given in Wolfram Language input format, so that you can read them back into the Wolfram Language. Sometimes, however, you may want to save expressions in other formats. You can do this by explicitly wrapping a format directive such as OutputForm around the expression you write out.
This writes an expression to the file tmp in output format:
The expression in tmp is now in output format:

Saving Definitions of Wolfram Language Objects

One of the most common reasons for using files is to save definitions of Wolfram Language objects, to be able to read them in again in a subsequent Wolfram Language session. The operators >> and >>> allow you to save Wolfram Language expressions in files. You can use the function Save to save complete definitions of Wolfram Language objects in a form suitable for execution in subsequent Wolfram Language sessions.
save the complete definitions for a symbol in a file
save definitions for symbols whose names match the string pattern form
save definitions for all symbols in the specified context
save definitions for several objects
Saving definitions in plain text files.
This assigns a value to the symbol a:
You can use Save to write the definition of a to a file:
Here is the definition of a that was saved in the file:
This defines a function f that depends on the symbol a previously defined:
This saves the complete definition of f in a file:
The file contains not only the definition of f itself, but also the definition of the symbol a on which f depends:
This clears the definitions of f and a:
You can reinstate the definitions you saved simply by reading in the file ffile:
The function Save makes use of the output forms Definition and FullDefinition, which print as definitions of Wolfram Language symbols. In some cases, you may find it convenient to use these output forms directly.
The output form Definition[f] prints as the sequence of definitions that have been made for f:
FullDefinition[f] includes definitions of the objects on which f depends:
When you define a new object in the Wolfram Language, your definition will often depend on other objects that you defined before. If you are going to be able to reconstruct the definition of your new object in a subsequent Wolfram Language session, it is important that you store not only its own definition, but also the definitions of other objects on which it depends. The function Save looks through the definitions of the objects you ask it to save, and automatically also saves all definitions of other objects on which it can see that these depend. However, in order to avoid saving a large amount of unnecessary material, Save never includes definitions for symbols that have the attribute Protected. It assumes that the definitions for these symbols are also built in. Nevertheless, with such definitions taken care of, it should always be the case that reading the output generated by Save back into a new Wolfram Language session will set up the definitions of your objects exactly as you had them before.

Saving Wolfram Language Definitions in Encoded Form

When you create files for input to the Wolfram Language, you usually want them to contain only "plain text", which can be read or modified directly. Sometimes, however, you may want the contents of a file to be "encoded" so that they cannot be read or modified directly as plain text, but can be loaded into the Wolfram Language. You can create encoded files using the Wolfram Language function Encode.
write an encoded version of the file source to the file dest
read in an encoded file
encode with the specified key
read in a file that was encoded with a key
create an encoded file that can only be read on a machine with a particular ID
Creating and reading encoded files.
This writes an expression in plain text to the file tmp:
This writes an encoded version of the file tmp to the file tmp.x:
Here are the contents of the encoded file. The only recognizable part is the special Wolfram Language comment at the beginning:
Even though the file is encoded, you can still read it into the Wolfram Language using the << operator:
save definitions for a symbol in internal Wolfram Language format
save definitions for all symbols in a context
save definitions for several symbols or contexts
save definitions in a file with a specially chosen name
Saving definitions in internal Wolfram System format.
If you have to read in very large or complicated definitions, you will often find it more efficient to store these definitions in internal Wolfram System format, rather than as text. You can do this using DumpSave.
This saves the definition for f in internal Wolfram System format:
You can still use << to read the definition in:
<< recognizes when a file contains definitions in internal Wolfram System format, and operates accordingly. One subtlety is that the internal Wolfram System format differs from one computer system to another. As a result, .mx files created on one computer cannot always be read on another.
If you use DumpSave["package`",] then the Wolfram Language will write out definitions to a file with a name like, where system identifies your type of computer system.
This creates a file with a name that reflects the name of the computer system being used:
<< automatically picks out the file with the appropriate name for your computer system:
External Programs
On most computer systems, you can execute external programs or commands from within the Wolfram Language. Often you will want to take expressions you have generated in the Wolfram Language, and send them to an external program, or take results from external programs, and read them into the Wolfram Language.
The Wolfram Language supports two basic forms of communication with external programs: structured and unstructured.
Structured communication
use WSTP to exchange expressions with WSTPcompatible external programs
Unstructured communication
use file reading and writing operations to exchange ordinary text
Two kinds of communication with external programs in the Wolfram Language.
The idea of structured communication is to exchange complete Wolfram Language expressions to external programs which are specially set up to handle such objects. The basis for structured communication is the Wolfram Symbolic Transfer Protocol (WSTP) system, discussed in "WSTP and External Program Communication".
Unstructured communication consists in sending and receiving ordinary text from external programs. The basic idea is to treat an external program very much like a file, and to support the same kinds of reading and writing operations.
read in a file
run an external command, and read in the output it produces
feed the textual form of expr to an external command
run an external command, and read in a list of the numbers it produces
Some ways to communicate with external programs.
In general, wherever you might use an ordinary file name, the Wolfram Language allows you instead to give a pipe, written as an external command, prefaced by an exclamation point. When you use the pipe, the Wolfram Language will execute the external command, and send or receive text from it.
This sends the result from FactorInteger to the external program lpr. On many Unix systems, this program generates a printout:
This executes the external command echo$TERM, then reads the result as Wolfram Language input:
With a textbased interface, putting ! at the beginning of a line causes the remainder of the line to be executed as an external command. squares is an external program which prints numbers and their squares.
In[1]:= !squares 4

1 1
2 4
3 9
4 16
This runs the external command squares 4, then reads numbers from the output it produces:
One point to notice is that you can get away with dropping the double quotes around the name of a pipe on the righthand side of << or >> if the name does not contain any spaces or other special characters.
Pipes in the Wolfram Language provide a very general mechanism for unstructured communication with external programs. On many computer systems, Wolfram Language pipes are implemented using pipe mechanisms in the underlying operating system; in some cases, however, other interprocess communication mechanisms are used. One restriction of unstructured communication in the Wolfram Language is that a given pipe can only be used for input or for output, and not for both at the same time. In order to do genuine twoway communication, you need to use WSTP.
Even with unstructured communication, you can nevertheless set up somewhat more complicated arrangements by using "temporary files". The basic idea is to write data to a file, then to read it as needed.
open a new file with a unique name in the default area for temporary files on your computer system
Opening a "temporary file".
Particularly when you work with temporary files, you may find it useful to be able to execute external commands which do not explicitly send or receive data from the Wolfram Language. You can do this using the Wolfram Language function Run.
run an external command from within the Wolfram Language
Running external commands without input or output.
This executes the external Unix command date. The returned value is an "exit code" from the operating system:
Note that when you use Run, you must not preface commands with exclamation points. Run simply takes the textual forms of the arguments you specify, then joins them together with spaces in between, and executes the resulting string as an external shell command.
It is important to realize that Run never "captures" any of the output from an external command. As a result, where this output goes is purely determined by your operating system. Similarly, Run does not supply input to external commands. This means that the commands can get input through any mechanism provided by your operating system. Sometimes external commands may be able to access the same input and output streams that are used by the Wolfram Language itself. In some cases, this may be what you want. But particularly if you are using the Wolfram Language with a front end, this can cause considerable trouble.
run command, using expr as input, and reading the output back into the Wolfram Language
Running Wolfram Language expressions through external programs.
As discussed above, << and >> cannot be used to both send and receive data from an external program at the same time. Nevertheless, by using temporary files, you can effectively both send and receive data from an external program while still using unstructured communication.
The function RunThrough writes the text of an expression to a temporary file, then feeds this file as input to an external program, and captures the output as input to the Wolfram Language. Note that in RunThrough, like Run, you should not preface the names of external commands with exclamation points.
This feeds the expression 789 to the external program cat, which in this case simply echoes the text of the expression. The output from cat is then read back into the Wolfram Language:
opens the specified file, URL or other target with the associated program on your computer system
Opening files with external programs.
This opens the URL using your system's preferred web browser:
SystemOpen uses settings in your operating system to determine how to open a URI or file. When opening files, it typically uses the same program that would be used if you double-clicked the file's icon.
Streams and LowLevel Input and Output
Files and pipes are both examples of general Wolfram System objects known as streams. A stream in the Wolfram System is a source of input or output. There are many operations that you can perform on streams.
You can think of >> and << as "highlevel" Wolfram System inputoutput functions. They are based on a set of lowerlevel inputoutput primitives that work directly with streams. By using these primitives, you can exercise more control over exactly how the Wolfram System does input and output. You will often need to do this, for example, if you write Wolfram System programs which store and retrieve intermediate data from files or pipes.
The basic lowlevel scheme for writing output to a stream in the Wolfram System is as follows. First, you call OpenWrite or OpenAppend to "open the stream", telling the Wolfram System that you want to write output to a particular file or external program, and in what form the output should be written. Having opened a stream, you can then call Write or WriteString to write a sequence of expressions or strings to the stream. When you have finished, you call Close to "close the stream".
a file, specified by name
a command, specified by name
an input stream
an output stream
Streams in the Wolfram System.
When you open a file or a pipe, the Wolfram System creates a "stream object" that specifies the open stream associated with the file or pipe. In general, the stream object contains the name of the file or the external command used in a pipe, together with a unique number.
The reason that the stream object needs to include a unique number is that in general you can have several streams connected to the same file or external program at the same time. For example, you may start several different instances of the same external program, each connected to a different stream.
Nevertheless, when you have opened a stream, you can still refer to it using a simple file name or external command name so long as there is only one stream associated with this object.
This opens an output stream to the file tmp:
This writes a sequence of expressions to the file:
Since you only have one stream associated with file tmp, you can refer to it simply by giving the name of the file:
This closes the stream:
Here is what was written to the file:
open an output stream to a file, wiping out the previous contents of the file
open an output stream to a new temporary file
open an output stream to a file, appending to what was already in the file
open an output stream to an external command
write a sequence of expressions to a stream, ending the output with a newline (line feed)
write a sequence of character strings to a stream, with no extra newlines
tell the Wolfram System that you are finished with a stream
Lowlevel output functions.
When you call Write[stream,expr], it writes an expression to the specified stream. The default is to write the expression in Wolfram System input form. If you call Write with a sequence of expressions, it will write these expressions one after another to the stream. In general, it leaves no space between the successive expressions. However, when it has finished writing all the expressions, Write always ends its output with a newline.
This reopens the file tmp:
This writes a sequence of expressions to the file, then closes the file:
All the expressions are written in input form. The expressions from a single Write are put on the same line:
Write provides a way of writing out complete Wolfram Language expressions. Sometimes, however, you may want to write out less structured data. WriteString allows you to write out any character string. Unlike Write, WriteString adds no newlines or other characters.
This opens the stream:
This writes two strings to the stream:
This writes another string, then closes the stream:
Here are the contents of the file. The strings were written exactly as specified, including only the newlines that were explicitly given:
write expressions to a list of streams
write strings to a list of streams
Writing output to lists of streams.
An important feature of the functions Write and WriteString is that they allow you to write output not just to a single stream, but also to a list of streams.
In using the Wolfram System, it is often convenient to define a channel which consists of a list of streams. You can then simply tell the Wolfram System to write to the channel, and have it automatically write the same object to several streams.
In a standard interactive Wolfram System session, there are several output channels that are usually defined. These specify where particular kinds of output should be sent. Thus, for example, $Output specifies where standard output should go, while $Messages specifies where messages should go. The function Print then works essentially by calling Write with the $Output channel. Message works in the same way by calling Write with the $Messages channel. "The Main Loop" lists the channels used in a typical Wolfram System session.
Note that when you run the Wolfram System through the Wolfram Symbolic Transfer Protocol (WSTP), a different approach is usually used. All output is typically written to a single WSTP link, but each piece of output appears in a "packet" which indicates what type it is.
In most cases, the names of files or external commands that you use in the Wolfram System correspond exactly with those used by your computers operating system. On some systems, however, the Wolfram System supports various streams with special names.
standard output
standard error
Special streams used on some computer systems.
The special stream "stdout" allows you to give output to the "standard output" provided by the operating system. Note however that you can use this stream only with simple textbased interfaces to the Wolfram System. If your interaction with the Wolfram System is more complicated, then this stream will not work, and trying to use it may cause considerable trouble.
option name
default value
the default output format to use
the width of the page in characters
whether to include ` marks in approximate numbers
encoding to be used for special characters
Some options for output streams.
You can associate a number of options with output streams. You can specify these options when you first open a stream using OpenWrite or OpenAppend.
This opens a stream, specifying that the default output format used should be OutputForm:
This writes expressions to the stream, then closes the stream:
The expressions were written to the stream in OutputForm:
Note that you can always override the output format specified for a particular stream by wrapping a particular expression you write to the stream with an explicit Wolfram System format directive, such as OutputForm or TeXForm.
The option PageWidth gives the width of the page available for textual output from the Wolfram System. All lines of output are broken so that they fit in this width. If you do not want any lines to be broken, you can set PageWidth->Infinity. Usually, however, you will want to set PageWidth to the value appropriate for your particular output device. On many systems, you will have to run an external program to find out what this value is. Using SetOptions, you can make the default rule for PageWidth be, for example, PageWidth:><<"!devicewidth", so that an external program is run automatically to find the value of the option.
This opens a stream, specifying that the page width is 20 characters:
This writes out an expression, then closes the stream:
The lines in the expression written out are all broken so as to be at most 20 characters long:
The option CharacterEncoding allows you to specify a character encoding that will be used for all strings which are sent to a particular output stream, whether by Write or WriteString. You will typically need to use CharacterEncoding if you want to modify an international character set, or prevent a particular output device from receiving characters that it cannot handle.
find the options that have been set for a stream
reset options for an open stream
Manipulating options of streams.
This opens a stream with the default settings for options:
This changes the FormatType option for the open stream:
Options shows the options you have set for the open stream:
This closes the stream again:
find the options set for all streams in the channel $Output
set options for all streams in the channel $Output
Manipulating options for the standard output channel.
At every point in your session, the Wolfram System maintains a list Streams[] of all the input and output streams that are currently open, together with their options. In some cases, you may find it useful to look at this list directly. The Wolfram System will not, however, allow you to modify the list, except indirectly through OpenRead and so on.
Naming and Finding Files

Directory Operations

The precise details of the naming of files differ from one computer system to another. Nevertheless, the Wolfram System provides some fairly general mechanisms that work on all systems.
The Wolfram System assumes that all your files are arranged in a hierarchy of directories. To find a particular file, the Wolfram System must know both what the name of the file is, and what sequence of directories it is in.
At any given time, however, you have a current working directory, and you can refer to files or other directories by specifying where they are relative to this directory. Typically you can refer to files or directories that are actually in this directory simply by giving their names, with no directory information.
your current working directory
set your current working directory
revert to your previous working directory
Manipulating directories.
This gives a string representing your current working directory:
This sets your current working directory to be the Examples subdirectory:
Now your current working directory is different:
This reverts to your previous working directory:
When you call SetDirectory, you can give any directory name that is recognized by your operating system. Thus, for example, on Unixbased systems, you can specify a directory one level up in the directory hierarchy using the notation .., and you can specify your "home" directory as ~.
Whenever you go to a new directory using SetDirectory, the Wolfram Language always remembers what the previous directory was. You can return to this previous directory using ResetDirectory. In general, the Wolfram Language maintains a stack of directories, given by DirectoryStack[]. Every time you call SetDirectory, it adds a new directory to the stack, and every time you call ResetDirectory it removes a directory from the stack.
the parent of your current working directory
the initial directory when the Wolfram System was started
your home directory, if this is defined
the base directory for systemwide files to be loaded by the Wolfram System
the base directory for userspecific files to be loaded by the Wolfram System
the toplevel directory in which your Wolfram System installation resides
Special directories.

Finding a File

Whenever you ask for a particular file, the Wolfram Language in general goes through several steps to try and find the file you want. The first step is to use whatever standard mechanisms exist in your operating system or shell.
The Wolfram Language scans the full name you give for a file, and looks to see whether it contains any of the "metacharacters" *, $, ~, ?, [, ", , and '. If it finds such characters, then it passes the full name to your operating system or shell for interpretation. This means that if you are using a Unixbased system, then constructions like name* and $VAR will be expanded at this point. But in general, the Wolfram Language takes whatever was returned by your operating system or shell, and treats this as the full file name.
For output files, this is the end of the processing that the Wolfram Language does. If the Wolfram Language cannot find a unique file with the name you specified, then it will proceed to create the file.
If you are trying to get input from a file, however, then there is another round of processing that the Wolfram Language does. What happens is that the Wolfram Language looks at the value of the Path option for the function you are using to determine the names of directories relative to which it should search for the file. The default setting for the Path option is the global variable $Path.
get a file, searching for it relative to the directories diri
default list of directories relative to which to search for input files
Search path for files.
In general, the global variable $Path is defined to be a list of strings, with each string representing a directory. Every time you ask for an input file, what the Wolfram Language effectively does is temporarily to make each of these directories in turn your current working directory, and then from that directory to try and find the file you have requested.
Here is a typical setting for $Path. The current directory (.) and your home directory (~) are listed first:
You can also use FindFile to locate a file.
find the file with the specified name that would be loaded by Get and related functions
determine whether the file exists
Finding a file on the $Path.
FindFile searches all directories in $Path and returns the absolute name of the file that would be loaded by Get, Needs, and other functions. FileExistsQ tests whether the file with the given name exists.
FindFile applied to a package name returns the absolute name of the init.m file from that package.

Listing Contents of Directories

list all files in your current working directory
list all files in your current working directory whose names match the string pattern form
list all files whose names match any of the formi
give the full names of all files whose names match forms in any of the directories diri
include files that are in subdirectories up to n levels down
include files in all subdirectories
give all files whose names match forms in any subdirectory of the directories in $Path
Getting lists of files in particular directories.
FileNames returns a list of strings corresponding to file names. When it returns a file that is not in your current directory, it gives the name of the file relative to the current directory. Note that all names are given in the format appropriate for the particular computer system on which they were generated.
Here is a list of all files in the current working directory whose names end with .m:
This lists files whose names start with a in the current directory, and in subdirectories with names that start with P:
The file name form you give to FileNames can use any of the Wolfram Language's string pattern objects, typically combined with the ~~ operator.
This gives a list of all files in your current working directory whose names match the form Test*.m:
This lists only those files with names of the form Test d.m, where d is a sequence of one or more digits:

Composing a File Name

extract the directory name from a file name
assemble a full file name from a directory name and a file name
give the parent of a directory
assemble a full file name from a hierarchy of directory names
assemble a single directory name from a hierarchy of directory names
Manipulating file names.
You should realize that different computer systems may give file names in different ways. Thus, for example, Windows systems typically give names in the form dir:dirdirname and Unix systems give names in the form dir/dir/name. The function FileNameJoin assembles file names in the appropriate way for the particular computer system you are using.
This gives the directory portion of the file name:
This constructs the full name of another file in the same directory as test.m:
split the file name into a list of directory and file names
extract part of the file name
drop parts of the file name
get the number of path elements in the file name
path name separator used in your operating system
Manipulating file names.
Functions like FileNameSplit and FileNameJoin provide additional operations on file names. They respect the file name separator used by your operating system and will split the file name appropriately. FileNameJoin will by default use the $PathnameSeparator to produce the name in a canonical form suitable for your operating system.
If you want to set up a collection of related files, it is often convenient to be able to refer to one file when you are reading another one. The global variable $InputFileName gives the name of the file from which input is currently being taken. Using DirectoryName and FileNameJoin you can then conveniently specify the names of other related files.
the name of the file from which input is currently being taken
Finding out how to refer to a file currently being read by the Wolfram Language.
One issue in handling files in the Wolfram Language is that the form of file and directory names varies between computer systems. This means, for example, that names of files that contain standard Wolfram Language packages may be quite different on different systems. Through a sequence of conventions, it is however possible to read in a standard Wolfram Language package with the same command on all systems. The way this works is that each package defines a socalled Wolfram Language context, of the form name`name`. On each system, all files are named in correspondence with the contexts they define. Then when you use the command <<name`name`, the Wolfram Language automatically translates the context name into the file name appropriate for your particular computer system.

Standard File Name Extensions

Wolfram Language expression file in plain text format
Wolfram System notebook file
Wolfram Language definitions in DumpSave format
Typical names of Wolfram System files.
If you use a notebook interface to the Wolfram System, then the Wolfram System front end allows you to save complete notebooks, including not only Wolfram Language input and output, but also text, graphics, and other material.
It is conventional to give Wolfram System notebook files names that end in .nb, and most versions of the Wolfram System enforce this convention.
the name for a file without its extension
the file extension for a file name
File name and extension.
You can use FileBaseName and FileExtension to extract the name of the file and its extension.
When you open a notebook in the Wolfram System front end, the Wolfram System will immediately display the contents of the notebook, but it will not normally send any of these contents to the kernel for evaluation until you explicitly request this to be done.
Within a Wolfram System notebook, however, you can use the Cell menu in the front end to identify certain cells as initialization cells, and if you do this, then the contents of these cells will automatically be evaluated whenever you open the notebook.
The I in the cell bracket indicates that the second cell is an initialization cell that will be evaluated whenever the notebook is opened.


It is sometimes convenient to maintain Wolfram System material both in a notebook which contains explanatory text, and in a package which contains only raw Wolfram Language definitions. You can do this by putting the Wolfram Language definitions into initialization cells in the notebook. Every time you save the notebook, the front end will then allow you to save an associated .m file that contains only the raw Wolfram Language definitions.
Manipulating Files and Directories
copy file1 to file2
give file1 the name file2
delete a file
give the number of bytes in a file
give the modification date for a file
set the modification date for a file to be the current date
give the type of a file as File, Directory, or None
Functions for manipulating files.
Different operating systems have different commands for manipulating files. The Wolfram Language provides a simple set of file manipulation functions, intended to work in the same way under all operating systems.
Notice that CopyFile and RenameFile give the final file the same modification date as the original one. FileDate returns modification dates in the {year,month,day,hour,minute,second} format used by DateList.
create a new directory
delete an empty directory
delete a directory and all files and directories it contains
rename a directory
copy a directory and all the files in it
Functions for manipulating directories.
Reading Textual Data
With <<, you can read files that contain Wolfram Language expressions given in input form. Sometimes, however, you may instead need to read files of data in other formats. For example, you may have data generated by an external program which consists of a sequence of numbers separated by spaces. This data cannot be read directly as Wolfram Language input. However, the function ReadList can take such data from a file or input stream, and convert it to a Wolfram Language list.
read a sequence of numbers from a file, and put them in a Wolfram Language list
Reading numbers from a file.
Here is a file of numbers:
This reads all the numbers in the file, and returns a list of them:
read numbers from a file, putting each successive pair into a separate list
put each successive block of n numbers in a separate list
put all the numbers on each line of the file into a separate list
Reading blocks of numbers.
This puts each successive pair of numbers from the file into a separate list:
This makes each line in the file into a separate list:
ReadList can handle numbers that are given in Fortranlike "E" notation. Thus, for example, ReadList will read 2.5E+5 as . Note that ReadList can handle numbers with any number of digits of precision.
Here is a file containing numbers in Fortranlike "E" notation:
ReadList can handle numbers in this form:
read a sequence of objects of a particular type
read at most n objects
Reading objects of various types.
ReadList can read not only numbers, but also a variety of other types of object. Each type of object is specified by a symbol such as Number.
Here is a file containing text:
This produces a list of the characters in the file, each given as a onecharacter string:
Here are the integer codes corresponding to each of the bytes in the file:
This puts the data from each line in the file into a separate list:
single byte of data, returned as an integer
single character, returned as a onecharacter string
approximate number in Fortranlike notation
exact or approximate number in Fortranlike notation
sequence of characters delimited by word separators
sequence of characters delimited by record separators
string terminated by a newline
complete Wolfram Language expression
complete Wolfram Language expression, returned inside Hold
Types of objects to read.
This returns a list of the "words" in the file strings:
ReadList allows you to read "words" from a file. It considers a "word" to be any sequence of characters delimited by word separators. You can set the option WordSeparators to specify the strings you want to treat as word separators. The default is to include spaces and tabs, but not to include, for example, standard punctuation characters. Note that in all cases successive words can be separated by any number of word separators. These separators are never taken to be part of the actual words returned by ReadList.
option name
default value
whether to make a separate list for the objects in each record
RecordSeparators{"\r\n", "\n","\r"}
separators for records
WordSeparators{" ","t"}
separators for words
whether to keep zerolength records
whether to keep zerolength words
words to take as tokens
Options for ReadList.
This reads the text in the file strings as a sequence of words, using the letter e and . as word separators:
The Wolfram Language considers any data file to consist of a sequence of records. By default, each line is considered to be a separate record. In general, you can set the option RecordSeparators to give a list of separators for records. Note that words can never cross record separators. As with word separators, any number of record separators can exist between successive records, and these separators are not considered to be part of the records themselves.
By default, each line of the file is considered to be a record:
Here is a file containing three "sentences" ending with periods:
This allows both periods and newlines as record separators:
This puts the words in each "sentence" into a separate list:
read the whole of a file as a single string
make a list of those parts of a file that lie between the lsepi and the rsepi
Settings for the RecordSeparators option.
Here is a file containing some text:
This reads all the text in the file source and returns it as a single string:
This gives a list of the parts of the file that lie between (: and :) separators:
By choosing appropriate separators, you can pick out specific parts of files:
The Wolfram Language usually allows any number of appropriate separators to appear between successive records or words. Sometimes, however, when several separators are present, you may want to assume that a "null record" or "null word" appears between each pair of adjacent separators. You can do this by setting the options NullRecords->True or NullWords->True.
Here is a file containing "words" separated by colons:
Here the repeated colons are treated as single separators:
Now repeated colons are taken to have null words in between:
In most cases, you want words to be delimited by separators that are not themselves considered as words. Sometimes, however, it is convenient to allow words to be delimited by special "token words", which are themselves words. You can give a list of such token words as a setting for the option TokenWords.
Here is some text:
This reads the text, using the specified token words to delimit words in the text:
You can use ReadList to read Wolfram Language expressions from files. In general, each expression must end with a newline, although a single expression may go on for several lines.
Here is a file containing text that can be used as Wolfram Language input:
This reads the text in exprs as Wolfram Language expressions:
This prevents the expressions from being evaluated:
ReadList can insert the objects it reads into any Wolfram Language expression. The second argument to ReadList can consist of any expression containing symbols such as Number and Word specifying objects to read. Thus, for example, ReadList["file",{Number,Number}] inserts successive pairs of numbers that it reads into lists. Similarly, ReadList["file",Hold[Expression]] puts expressions that it reads inside Hold.
If ReadList reaches the end of your file before it has finished reading a particular set of objects you have asked for, then it inserts the special symbol EndOfFile in place of the objects it has not yet read.
Here is a file of numbers:
The symbol EndOfFile appears in place of numbers that were needed after the end of the file was reached:
execute a command, and read its output
read any input stream
Reading from commands and streams.
This executes the Unix command date, and reads its output as a string:
open a file for reading
open a pipe for reading
read an object of the specified type from a stream
skip over an object of the specified type in an input stream
skip over n objects of the specified type in an input stream
close an input stream
Functions for reading from input streams.
ReadList allows you to read all the data in a particular file or input stream. Sometimes, however, you want to get data a piece at a time, perhaps doing tests to find out what kind of data to expect next.
When you read individual pieces of data from a file, the Wolfram Language always remembers the "current point" that you are at in the file. When you call OpenRead, the Wolfram Language sets up an input stream from a file, and makes your current point the beginning of the file. Every time you read an object from the file using Read, the Wolfram Language sets your current point to be just after the object you have read. Using Skip, you can advance the current point past a sequence of objects without actually reading the objects.
Here is a file of numbers:
This opens an input stream from the file:
This reads the first number from the file:
This reads the second pair of numbers:
This skips the next number:
This reads the remaining numbers:
This closes the input stream:
You can use the options WordSeparators and RecordSeparators in Read and Skip just as you do in ReadList.
Note that if you try to read past the end of file, Read returns the symbol EndOfFile.
Searching Files
get a list of all the lines in the file that contain the specified text
get a list of the first n lines that contain the specified text
get lines that contain any of the texti
Finding lines that contain specified text.
Here is a file containing some text:
This returns a list of all the lines in the file containing the text is:
The text fourth appears nowhere in the file:
By default, FindList scans successive lines of a file, and returns those lines which contain the text you specify. In general, however, you can get FindList to scan successive records, and return complete records which contain specified text. As in ReadList, the option RecordSeparators allows you to tell the Wolfram Language what strings you want to consider as record separators. Note that by giving a pair of lists as the setting for RecordSeparators, you can specify different left and right separators. By doing this, you can make FindList search only for text which is between specific pairs of separators.
This finds all "sentences" ending with a period which contain And:
option name
default value
separators for records
whether to require the text searched for to be at the beginning of a record
WordSeparators{" ","t"}
separators for words
whether to require that the text searched for appear as a word
whether to treat lowercase and uppercase letters as equivalent
Options for FindList.
This finds only the occurrence of Here which is at the beginning of a line in the file:
In general, FindList finds text that appears anywhere inside a record. By setting the option WordSearch->True, however, you can tell FindList to require that the text it is looking for appears as a separate word in the record. The option WordSeparators specifies the list of separators for words.
The text th does appear in the file, but not as a word. As a result, the FindList fails:
search for occurrences of the text in any of the filei
Searching in multiple files.
This searches for third in two copies of textfile:
It is often useful to call FindList on lists of files generated by functions such as FileNames.
run an external command, and find text in its output
Finding text in the output from an external program.
This runs the external Unix command date in a text-based interface:
This finds the timeofday field in the date:
open a file for reading
open a pipe for reading
find the next occurrence of text
close an input stream
Finding successive occurrences of text.
FindList works by making one pass through a particular file, looking for occurrences of the text you specify. Sometimes, however, you may want to search incrementally for successive occurrences of a piece of text. You can do this using Find.
In order to use Find, you first explicitly have to open an input stream using OpenRead. Then, every time you call Find on this stream, it will search for the text you specify, and make the current point in the file be just after the record it finds. As a result, you can call Find several times to find successive pieces of text.
This opens an input stream for textfile:
This finds the first line containing And:
Calling Find again gives you the next line containing And:
This closes the input stream:
Once you have an input stream, you can mix calls to Find, Skip, and Read. If you ever call FindList or ReadList, the Wolfram Language will immediately read to the end of the input stream.
This opens the input stream:
This finds the first line which contains second, and leaves the current point in the file at the beginning of the next line:
Read can then read the word that appears at the beginning of the line:
This skips over the next three words:
The Wolfram Language finds is in the remaining text, and prints the entire record as output:
This closes the input stream:
find the position of the current point in an open stream
set the position of the current point
set the current point to the beginning of a stream
set the current point to the end of a stream
Finding and setting the current point in a stream.
Functions like Read, Skip, and Find usually operate on streams in an entirely sequential fashion. Each time one of the functions is called, the current point in the stream moves on.
Sometimes, you may need to know where the current point in a stream is, and be able to reset it. On most computer systems, StreamPosition returns the position of the current point as an integer giving the number of bytes from the beginning of the stream.
This opens the stream:
When you first open the file, the current point is at the beginning, and StreamPosition returns 0:
This reads the first line in the file:
Now the current point has advanced:
This sets the stream position back:
Now Read returns the remainder of the first line:
This closes the stream:
Searching and Reading Strings
Functions like Read and Find are most often used for processing text and data from external files. In some cases, however, you may find it convenient to use these same functions to process strings within the Wolfram Language. You can do this by using the function StringToStream, which opens an input stream that takes characters not from an external file, but instead from a Wolfram Language string.
open an input stream for reading from a string
close an input stream
Treating strings as input streams.
This opens an input stream for reading from the string:
This reads the first "word" from the string:
This reads the remaining words from the string:
This closes the input stream:
Input streams associated with strings work just like those with files. At any given time, there is a current position in the stream, which advances when you use functions like Read. The current position is given as the number of characters from the beginning of the string by the function StreamPosition[stream]. You can explicitly set the current position using SetStreamPosition[stream,n].
Here is an input stream associated with a string:
The current position is initially 0 characters from the beginning of the string:
This reads a number from the stream:
The current position is now 3 characters from the beginning of the string:
This sets the current position to be 1 character from the beginning of the string:
If you now read a number from the string, you get the 23 part of 123:
This sets the current position to the end of the string:
If you now try to read from the stream, you will always get EndOfFile:
This closes the stream:
Particularly when you are processing large volumes of textual data, it is common to read fairly long strings into the Wolfram Language, then to use StringToStream to allow further processing of these strings within the Wolfram Language. Once you have created an input stream using StringToStream, you can read and search the string using any of the functions discussed for files.
This puts the whole contents of textfile into a string:
This opens an input stream for the string:
This gives the lines of text in the string that contain is:
This resets the current position back to the beginning of the string:
This finds the first occurrence of the in the string, and leaves the current point just after it:
This reads the "word" which appears immediately after the:
This closes the input stream:
Binary Files
Functions like Read and Write handle ordinary printable text. But in dealing with external data files or devices it is sometimes necessary to go to a lower level, and work directly with raw binary data. You can do this using BinaryRead and BinaryWrite.
read one byte
read an object of the specified type
read a list of objects
write one byte
write a sequence of bytes
write the characters in a string
write an object of the specified type
write a sequence of objects
write objects of different types
Reading and writing binary data.
8bit unsigned integer
8bit character
16bit character
IEEE singleprecision complex number
IEEE doubleprecision complex number
IEEE quadprecision complex number
8bit signed integer
16bit signed integer
32bit signed integer
64bit signed integer
128bit signed integer
IEEE singleprecision real number
IEEE doubleprecision real number
IEEE quadprecision real number
nullterminated string of 8bit characters
8bit unsigned integer
16bit unsigned integer
32bit unsigned integer
64bit unsigned integer
128bit unsigned integer
Types supported in BinaryRead and BinaryWrite.
This writes a sequence of bytes to a file:
BinaryWrite automatically opens a stream for the file. This closes it:
This reads the first byte from the file, returning it as an integer:
This reads the second 8 bits in the file as a character:
This reads the next 32 bits as a 32bit integer:
Like Read and Write, BinaryRead and BinaryWrite work with streams. But if you give a file name, they automatically open the specified file as a stream. To create a stream directly you can use OpenRead or OpenWrite. On some computer systems, the option setting BinaryFormat->True is required for any stream to be used with BinaryRead and BinaryWrite, in order to prevent possible corruption from such issues as newline translation.
In using the Wolfram Language you are normally completely insulated from the raw representation of data inside your computer. But with BinaryRead and BinaryWrite this is no longer so. One of the subtleties that then arises is that different computers may take the bytes that make up numbers to be in different orders, as specified by their setting for $ByteOrdering.
This writes a 32bit integer to a file:
This closes the file:
This reads the integer back, but assumes an opposite byte ordering:
read all the bytes in a file
read all the data, treating it as objects of a certain type
treat the data as objects of a sequence of types
read only the first n objects
Reading complete binary files.
This writes out a 128bit real number:
This reads back the bytes in the number:
This reads back the bytes as a sequence of 32bit real numbers:
This treats the data as pairs containing a byte and a 32bit real:
BinaryRead and BinaryWrite allow complete flexibility in reading and writing raw binary data. But in many practical applications one instead wants to work only with particular predefined formats. You can do this using Import and Export.
In addition to many complex formats, Import and Export support files containing sequences of identical data elements, of the same types as in BinaryRead and BinaryWrite. They also support the "Bit" format, consisting of individual binary bits, represented as 0 or 1.
Generating C and Fortran Expressions
If you have specialpurpose programs written in C or Fortran, you may want to take formulas you have generated in the Wolfram Language and insert them into the source code of your programs. The Wolfram Language allows you to convert mathematical expressions into C and Fortran expressions.
write out expr so it can be used in a C program
write out expr for Fortran
write out a C function that computes expr
Wolfram Language output for programming languages.
Here is an expression, written out in standard Wolfram Language form:
Here is the expression in Fortran form:
Here is the same expression in C form. Macros for objects like Power are defined in the C header file mdefs.h that comes with most versions of the Wolfram Language:
If you want to generate a C version of an entire expression you can do this with Export to C.
Here an entire C function is computed from a Wolfram Language CompiledFunction expression:
One of the common motivations for converting Wolfram Language expressions into C or Fortran is to try to make them faster to evaluate numerically. But the single most important reason that C and Fortran can potentially be more efficient than the Wolfram Language is that in these languages the user always specifies up front what type each variable will beinteger, real number, array, and so on.
The Wolfram Language function Compile makes such assumptions within the Wolfram Language, and generates highly efficient internal code. This can be made to run even faster by setting the CompilationTarget to "C".
compile an expression into efficient internal code
compile into C code and link back into the Wolfram Language
Compiling Wolfram Language expressions.
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 Get. This function can also be used programmatically in your code or other .wl files.
read in a file and evaluate commands in it
shorter form of Get
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 performedfor 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\{First[{}]}\wolfram" -script file.wl
Running the script file on Windows.
$ /Applications/ -script file.wl
Running the script file on macOS.
$ wolfram -script file.wl
Running the script on Linux.
The -script 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 PageWidth option of the output functions to Infinity and prints no In[] and Out[] labels. When run in this mode, the standard input and output channels , , and are not redirected, and numbers are formatted in InputForm.
Running wolfram with the -script option is equivalent to reading the file using the 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 WolframScript interpreter as follows. The -file flag is optional.
$ wolframscript -file file.wl
Running the script using WolframScript.
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 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 WolframScript page.
On Windows and Linux, 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 WolframScript. These installers will place wolframscript on the PATH by default.

Unix Script Executables

Unix-like operating systemsas well as Unix environments for Windows such as cygwin and MinGWallow 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 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[
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 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 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 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 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 $ScriptCommandLine. Additionally, the contents of standard input are available to be processed as a string in the variable $ScriptInputString.
the command line that launched the script
the contents of standard input given to the script
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[
{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 $ScriptCommandLine is a list containing the name of the script as the first element and the rest of the command line arguments. $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 $ScriptCommandLine is set to a non-empty list only if the Wolfram Language kernel is invoked via 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 $ScriptCommandLine==={}. Then, either $ScriptCommandLine or $CommandLine should be used to access the command-line arguments.