Public API

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.

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.

installkernel(name::AbstractString, options::AbstractString...;
              julia::Cmd,
              specname::AbstractString,
              displayname::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 displayname argument can be used to customize the name displayed in the Jupyter kernel list.

The returned kernelpath is the path of the installed kernel directory, something like /...somepath.../kernels/julia-o3-1.6 (in Julia 1.6). The specname argument can be passed to alter the name of this directory (which defaults to name with spaces replaced by hyphens, and special characters other than - hyphen, . period and _ underscore replaced by _ underscores, and the Julia major and minor version appended).

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

You can specify a custom command to execute Julia via keyword argument julia. For example, you may want specify that the Julia kernel is running in a Docker container (but Jupyter will run outside of it), by calling installkernel from within such a container instance like this (or similar):

installkernel(
    "Julia via Docker",
    julia = `docker run --rm --net=host
        --volume=/home/USERNAME/.local/share/jupyter:/home/USERNAME/.local/share/jupyter
        some-container /opt/julia-1.x/bin/julia`
)

jupyterlab(args=``; dir=homedir(), detached=false, port::Union{Nothing,Int}=nothing, verbose=false)

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

notebook(args=``; dir=homedir(), detached=false, port::Union{Nothing,Int}=nothing, verbose=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.

Extra arguments can be passed with the args argument, e.g. notebook(`--help`; verbose=true) to see the command help. 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.)

When the optional keyword port is not nothing, open the notebook on the given port number.

If verbose=true then the stdout/stderr from Jupyter will be echoed to the terminal. Try enabling this if you're having problems connecting to a kernel to see if there's any useful error messages from Jupyter.

For launching a JupyterLab instance, see IJulia.jupyterlab().

qtconsole()

Launches qtconsole for the current kernel. IJulia must be initialized already.

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.

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.

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.

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.

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.

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.

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.

reset_stdio_count()

Reset the count of the number of bytes written to stdout/stderr. See set_max_stdio for more details.

push_preexecute_hook(f::Function)

Push a function f() onto the end of a list of functions to execute before 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.

push_postexecute_hook(f::Function)

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

pop_postexecute_hook(f::Function)

Remove a function f() from the list of functions to execute after 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.

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.

init_matplotlib(backend="widget")

Initialize the integration with matplotlib.

init_ipywidgets()

Initialize the integration with ipywidgets by setting up the right hooks to allow ipywidgets to use IJulia comms.

init_ipython()

Initialize the integration with IPython by overriding its display system to call Julia's display() instead.