IJulia is a Julia-language backend combined with the Jupyter interactive environment (also used by IPython). This combination allows you to interact with the Julia language using Jupyter/IPython's powerful graphical notebook, which combines code, formatted text, math, and multimedia in a single document.

The IJulia module is used in three ways

• Typing using IJulia; notebook() will launch the Jupyter notebook interface in your web browser. This is an alternative to launching jupyter notebook directly from your operating-system command line.

• In a running notebook, the IJulia module is loaded and IJulia.somefunctions can be used to interact with the running IJulia kernel:

  • IJulia.load(filename) and IJulia.load_string(s) load the contents of a file or a string, respectively, into a notebook cell.
  • IJulia.clear_output() to clear the output from the notebook cell, useful for simple animations.
  • IJulia.clear_history() to clear the history variables In and Out.
  • push_X_hook(f) and pop_X_hook(f), where X is either preexecute, postexecute, or posterror. This allows you to insert a "hook" function into a list of functions to execute when notebook cells are evaluated.
  • IJulia.set_verbose() enables verbose output about what IJulia is doing internally; this is mainly used for debugging.

• It is used internally by the IJulia kernel when talking to the Jupyter server.

In is a global dictionary of input strings, where In[n] returns the string for input cell n of the notebook (as it was when it was last evaluated).

Out is a global dictionary of output values, where Out[n] returns the output from the last evaluation of cell n in the notebook.

ans is a global variable giving the value returned by the last notebook cell evaluated.

The IJulia kernel captures all stdout and stderr output and redirects it to the notebook. When debugging IJulia problems, however, it can be more convenient to not capture stdout and stderr output (since the notebook may not be functioning). This can be done by editing IJulia.jl to set capture_stderr and/or capture_stdout to false.

MIME types that when rendered (via stringmime) return JSON data. See ijulia_mime_types for a description of how MIME types are selected.

This is necessary to embed the JSON as is in the displaydata bundle (rather than as stringify'd JSON).

A vector of MIME types (or vectors of MIME types) that IJulia will try to render. IJulia will try to render every MIME type specified in the first level of the vector. If a vector of MIME types is specified, IJulia will include only the first MIME type that is renderable (this allows for the expression of priority and exclusion of redundant data).

For example, since "text/plain" is specified as a first-child of the array, IJulia will always try to include a "text/plain" representation of anything that is displayed. Since markdown and html are specified within a sub-vector, IJulia will always try to render "text/markdown", and will only try to render "text/html" if markdown isn't possible.

inited is a global variable that is set to true if the IJulia kernel is running, i.e. in a running IJulia notebook. To test whether you are in an IJulia notebook, therefore, you can check isdefined(Main, :IJulia) && IJulia.inited.

IJulia.n is the (integer) index of the last-evaluated notebook cell.

clear_history([indices])

The clear_history() function clears all of the input and output history stored in the running IJulia notebook. This is sometimes useful because all cell outputs are remember in the Out global variable, which prevents them from being freed, so potentially this could waste a lot of memory in a notebook with many large outputs.

The optional indices argument is a collection of indices indicating a subset of cell inputs/outputs to clear.

clear_output(wait=false)

Call clear_output() to clear visible output from the current notebook cell. Using wait=true clears the output only when new output is available, which reduces flickering and is useful for simple animations.

Generate a dictionary of mime_type => data pairs for all registered MIME types. This is the format that Jupyter expects in displaydata and executeresult messages.

Generate the preferred json-MIME representation of x.

Returns a tuple with the selected MIME type and the representation of the data using that MIME type (as a JSONText).

Generate the preferred MIME representation of x.

Returns a tuple with the selected MIME type and the representation of the data using that MIME type.

history([io], [indices...])

The history() function prints all of the input history stored in the running IJulia notebook in a format convenient for copying.

The optional indices argument is one or more indices or collections of indices indicating a subset input cells to print.

The optional io argument is for specifying an output stream. The default is stdout.

installkernel(name::AbstractString, options::AbstractString...;
              specname::AbstractString,
              env=Dict())

Install a new Julia kernel, where the given options are passed to the julia executable, the user-visible kernel name is given by name followed by the Julia version, and the env dictionary is added to the environment.

The new kernel name is returned by installkernel. For example:

kernelpath = installkernel("Julia O3", "-O3", env=Dict("FOO"=>"yes"))

creates a new Julia kernel in which julia is launched with the -O3 optimization flag and FOO=yes is included in the environment variables.

The returned kernelpath is the path of the installed kernel directory, something like /...somepath.../kernels/julia-O3-1.0 (in Julia 1.0). The specname argument can be passed to alter the name of this directory (which defaults to name with spaces replaced by hyphens).

You can uninstall the kernel by calling rm(kernelpath, recursive=true).

jupyterlab(; dir=homedir(), detached=false)

Similar to IJulia.notebook() but launches JupyterLab instead of the Jupyter notebook.

load(filename, replace=false)

Load the file given by filename into a new input code cell in the running IJulia notebook, analogous to the %load magics in IPython. If the optional argument replace is true, then the file contents replace the current cell rather than creating a new cell.

load_string(s, replace=false)

Load the string s into a new input code cell in the running IJulia notebook, somewhat analogous to the %load magics in IPython. If the optional argument replace is true, then s replaces the current cell rather than creating a new cell.

notebook(; dir=homedir(), detached=false)

The notebook() function launches the Jupyter notebook, and is equivalent to running jupyter notebook at the operating-system command-line. The advantage of launching the notebook from Julia is that, depending on how Jupyter was installed, the user may not know where to find the jupyter executable.

By default, the notebook server is launched in the user's home directory, but this location can be changed by passing the desired path in the dir keyword argument. e.g. notebook(dir=pwd()) to use the current directory.

By default, notebook() does not return; you must hit ctrl-c or quit Julia to interrupt it, which halts Jupyter. So, you must leave the Julia terminal open for as long as you want to run Jupyter. Alternatively, if you run notebook(detached=true), the jupyter notebook will launch in the background, and will continue running even after you quit Julia. (The only way to stop Jupyter will then be to kill it in your operating system's process manager.)

If d ends with an incomplete UTF8-encoded character, return the number of trailing incomplete bytes. Otherwise, return 0.

pop_posterror_hook(f::Function)

Remove a function f() from the list of functions to execute after an error occurs when a notebook cell is evaluated.

pop_postexecute_hook(f::Function)

Remove a function f() from the list of functions to execute after executing any notebook cell.

pop_preexecute_hook(f::Function)

Remove a function f() from the list of functions to execute before executing any notebook cell.

pop_posterror_hook(f::Function)

Remove a function f() from the list of functions to execute after an error occurs when a notebook cell is evaluated.

push_postexecute_hook(f::Function)

Push a function f() onto the end of a list of functions to execute after executing any notebook cell.

push_preexecute_hook(f::Function)

Push a function f() onto the end of a list of functions to execute before executing any notebook cell.

readprompt(prompt::AbstractString; password::Bool=false)

Display the prompt string, request user input, and return the string entered by the user. If password is true, the user's input is not displayed during typing.

Jupyter associates cells with message headers. Once a cell's execution state has been set as to idle, it will silently drop stream messages (i.e. output to stdout and stderr) - see https://github.com/jupyter/notebook/issues/518. When using Interact, and a widget's state changes, a new message header is sent to the IJulia kernel, and while Reactive is updating Signal graph state, it's execution state is busy, meaning Jupyter will not drop stream messages if Interact can set the header message under which the stream messages will be sent. Hence the need for this function.

set_max_stdio(max_output::Integer)

Sets the maximum number of bytes, max_output, that can be written to stdout and stderr before getting truncated. A large value here allows a lot of output to be displayed in the notebook, potentially bogging down the browser.

set_verbose(v=true)

This function enables (or disables, for set_verbose(false)) verbose output from the IJulia kernel, when called within a running notebook. This consists of log messages printed to the terminal window where jupyter was launched, displaying information about every message sent or received by the kernel. Used for debugging IJulia.

Continually read from (size limited) Libuv/OS buffer into an IObuffer to avoid problems when the Libuv/OS buffer gets full (https://github.com/JuliaLang/julia/issues/8789). Send data immediately when buffer contains more than max_bytes bytes. Otherwise, if data is available it will be sent every stream_interval seconds (see the Timers set up in watchstdio). Truncate the output to `maxoutputperrequest` bytes per execution request since excessive output can bring browsers to a grinding halt.