utop — a universal toplevel (i.e., REPL) for OCaml

utop is an improved toplevel (i.e., Read-Eval-Print Loop) for OCaml. It can run in a terminal or in Emacs. It supports line editing, history, real-time and context sensitive completion, colors, and more.

It integrates with the Tuareg, caml, ReasonML and typerex modes in Emacs.

Features

• Context-sensitive completion — utop uses the compiler libraries to provide completions for function names, argument labels, constructors, record fields, and method names. Suggestions are displayed dynamically as you type.
• Syntax highlighting in the terminal (can be enabled via utoprc).
• Automatic Lwt/Async evaluation — toplevel expressions that return Lwt.t or Async.Deferred.t values are automatically run, so you don't have to wrap them in Lwt_main.run or Thread_safe.block_on_async_exn yourself. This can be toggled with UTop.set_auto_run_lwt and UTop.set_auto_run_async.
• #typeof directive — inspect the types of values, modules, and module types directly from the REPL (e.g. #typeof "List";;).
• Short paths by default — type output uses -short-paths so you see concise type names instead of fully-qualified internal paths.
• Automatic toplevel printer installation — libraries that annotate their pretty-printers with [@@ocaml.toplevel_printer] get their printers loaded automatically (see below).
• Vi edit mode — an optional vi-style editing mode (see below).
• Built on Lambda-term and Zed, two OCaml libraries for terminal UI and text editing.

Installation via opam

The easiest and recommended way of installing utop is via opam:

opam install utop

If you want to build it manually, refer to the opam file which lists the dependencies.

Installation from sources

To build and install utop:

make
make install

Documentation and manual pages (optional)

To build the documentation (currently broken):

make doc

It will then be installed by make install.

Tests (optional)

To build and execute tests (currently broken):

make test

Usage

To use utop, simply run:

utop

The prompt

The default prompt in the terminal displays a two-line header:

─( 10:30:42 )─< command 1 >───────────────────────{ counter: 0 }─
utop #

• Time — the current time when the command was entered.
• Command number — incremented after each toplevel phrase is evaluated.
• Counter — the Emacs-style keyboard macro counter (see C-x C-k C-c in the Lambda-term documentation). When you are recording a macro, a macro: N indicator also appears showing the number of recorded keystrokes.
• Key sequence — if you are in the middle of a multi-key chord, the keys entered so far are displayed in the header.

You can switch to a simpler prompt with #utop_prompt_simple;; (shows utop [N]: ) or a bare prompt with #utop_prompt_dummy;; (shows # ). Use #utop_prompt_fancy_light;; or #utop_prompt_fancy_dark;; to switch the color profile of the default prompt.

Completion bar

utop displays a bar after the prompt which is used to show possible completions in real time. You can navigate in it using M-left and M-right, and select one completion using M-down. The M denotes the meta key, which is Alt on most systems.

You can disable the completion bar with:

UTop.set_show_box false

Directives

In addition to the standard OCaml toplevel directives, utop provides:

Directive	Description
#utop_bindings	List all current key bindings
#utop_macro	Display the currently recorded macro
#utop_stash	Save all valid commands from the session to a file
#utop_save	Save the session with a simple prompt to a file
#utop_prompt_simple	Switch to a minimal utop [N]: prompt
#utop_prompt_dummy	Switch to a bare # prompt (no colors, no info line)
#utop_prompt_fancy_light	Use the fancy prompt with a light color profile
#utop_prompt_fancy_dark	Use the fancy prompt with a dark color profile
#typeof "X"	Show the type of a value, module, or module type
#topfind_log	Display messages recorded from findlib
#topfind_verbose	Toggle findlib verbosity

Customization

Colors

To add colors to utop, copy one of the files utoprc-dark or utoprc-light to ~/.config/utop/utoprc. utoprc-dark is for terminals with dark colors (such as white on black) and utoprc-light is for terminals with light colors (such as black on white).

Prompt

You can customize the prompt of utop by setting the reference UTop.prompt. Several built-in prompt styles are available via directives — see the Directives table above. To make a prompt change permanent, add the directive to ~/.config/utop/init.ml:

#utop_prompt_simple;;

Key bindings

Key bindings in the terminal can be changed by writing a ~/.config/lambda-term-inputrc file. For example:

[read-line]
C-left: complete-bar-prev
C-right: complete-bar-next
C-down: complete-bar

If manual pages are correctly installed you can see a description of this file by executing:

$ man 5 lambda-term-inputrc

Vi edit mode

You can turn on the vi edit mode by #edit_mode_vi. It currently supports three vi modes: normal, insert, visual mode, and you can get/set content with vim-like registers.

This special edit mode is evolving rapidly; see the CHANGES of lambda-term for the rapidly changing information.

UTop API

UTop exposes several more settings through its API; see documentation.

Integration with Emacs

Overview

utop.el is a package that provides utop integration with Emacs. The package allows you to run utop inside Emacs and to evaluate code in it straight from your source buffers (with the help of utop-minor-mode).

Those features are covered in more details in the "Usage" section.

Requirements

utop.el requires Emacs 26.1 or newer. You'll also have to install utop and make sure it's on Emacs's exec-path, so that it could be started from within Emacs.

Main setup

The recommended way to install utop.el is via Emacs's built-in package manager package.el.

utop.el is available on the community-maintained MELPA Stable and MELPA package.el repositories. If you're not using them already, please follow the setup instructions here.

Note: Using MELPA Stable is recommended as it has the latest stable version. MELPA has a development snapshot for users who don't mind breakage but don't want to run utop.el from a git checkout.

Once you've enabled MELPA (Stable), you can install utop.el using the following command:

M-x package-install [RET] utop [RET]

or if you'd rather keep it in your Emacs config:

(unless (package-installed-p 'utop)
  (package-refresh-contents)
  (package-install 'utop))

use-package users can do something like this:

(use-package utop
  :ensure t)

If the installation doesn't work try refreshing the package list:

M-x package-refresh-contents

Alternatively, if you have installed utop via opam, you can add this to your ~/.emacs:

;; Add the opam lisp dir to the Emacs load path
(add-to-list
 'load-path
 (replace-regexp-in-string
  "\n" "/share/emacs/site-lisp"
  (shell-command-to-string "opam var prefix")))

;; Automatically load utop.el
(autoload 'utop "utop" "Toplevel for OCaml" t)

In any case, if you installed utop via opam you should add this to your ~/.emacs:

;; Use the opam installed utop
(setq utop-command "opam exec -- utop -emacs")

If you use dune and want to launch dune utop in emacs, you should add this to your ~/.emacs:

(setq utop-command "opam exec -- dune utop . -- -emacs")

Usage

You can start utop inside Emacs with: M-x utop.

utop.el also ships with a minor mode that has the following key-bindings:

key-binding	function	Description
C-c C-s	utop	Start a utop buffer
C-x C-e	utop-eval-phrase	Evaluate the current phrase
C-x C-r	utop-eval-region	Evaluate the selected region
C-c C-b	utop-eval-buffer	Evaluate the current buffer
C-c C-k	utop-kill	Kill a running utop process
C-c C-z	utop-switch-to-repl	Switch to utop process

You can enable the minor mode using M-x utop-minor-mode, or you can have it enabled by default with the following configuration:

(autoload 'utop-minor-mode "utop" "Minor mode for utop" t)
(add-hook 'tuareg-mode-hook 'utop-minor-mode)

If you plan to use utop with another major-mode than tuareg, replace tuareg-mode-hook by the appropriate hook. The utop minor mode will work out of the box with these modes: tuareg-mode, caml-mode, reason-mode and typerex-mode. For other modes you will need to set the following three variables:

• utop-skip-blank-and-comments
• utop-skip-to-end-of-phrase
• utop-discover-phrase

You can also complete text in a buffer using the environment of the toplevel. For that bind the function utop-edit-complete to the key you want.

Troubleshooting

If you get this error when running utop in a terminal or in Emacs this means that the environment variable CAML_LD_LIBRARY_PATH is not set correctly:

Fatal error: cannot load shared library dlllwt-unix_stubs
Reason: dlopen(dlllwt-unix_stubs.so, 138): image not found

It should point to the directory stublibs inside your ocaml installation.

Automatically installing toplevel printers

Utop will automatically install toplevel printers for custom types if their interface files are marked with an [@@ocaml.toplevel_printer] attribute. Adding this annotation to your libraries will remove the need to have a separate top package to install the printers.

For example, in the uri library, the old printing function for Uri.t was:

val pp_hum : Format.formatter -> t -> unit

Just adding this annotation results in Uri.t values being automatically pretty printed in this version of utop.

val pp_hum : Format.formatter -> t -> unit [@@ocaml.toplevel_printer]

There should be no downsides to adding this attribute to your libraries, so we encourage community library maintainers to use this attribute to improve the out-of-the-box experience for users of their libraries within utop.

Creating a custom utop-enabled toplevel

With Dune

The recommended way to build a custom utop toplevel is via Dune. The entry point of the custom utop must call UTop_main.main. For instance, write the following myutop.ml file:

let () = UTop_main.main ()

and the following dune file:

(executable
 (name myutop)
 (link_flags -linkall)
 (libraries utop))

then, to build the toplevel, run:

$ dune myutop.bc

Note the -linkall in the link flags. By default OCaml doesn't link unused modules. However for a toplevel you don't know in advance what the user is going to use so you must link everything.

If you want to include more libraries in your custom utop, simply add them to the (libraries ...) field.

Additionally, if you want to install this toplevel, add the two following fields to the executable stanza:

  (public_name myutop)
  (modes byte)

The (modes ...) field is to tell dune to install the byte-code version of the executable, as currently native toplevels are not fully supported.

Manually, with ocamlfind

This section describe methods using ocamlfind. These are no longer tested, so there is no guarantee they still work.

If you want to create a custom toplevel with utop instead of the classic one you need to link it with utop and its dependencies and call UTop_main.main in the last linked unit. You also need to pass the -thread switch when linking the toplevel.

The easiest way to do that is by using ocamlfind:

$ ocamlfind ocamlmktop -o myutop -thread -linkpkg -package utop myutop_main.cmo

Where myutop_main.ml contains:

let () = UTop_main.main ()

You can also use the ocamlc sub-command instead of ocamlmktop. In this case you need to pass these three extra arguments:

• -linkall to be sure all units are linked into the produced toplevel
• -package compiler-libs.toplevel
• -predicates create_toploop

With the last option ocamlfind will generate a small ocaml unit, linked just before myutop_main.cmo, which will register at startup packages already linked in the toplevel so they are not loaded again by the #require directive. It does the same with the ocamlmktop sub-command.

For example:

$ ocamlfind ocamlc -o myutop -thread -linkpkg -linkall -predicates create_toploop \
    -package compiler-libs.toplevel,utop myutop.cmo

Note that if you are not using ocamlfind, you will need to do that yourself. You have to call Topfind.don't_load with the list of all packages linked with the toplevel.

A full example using ocamlbuild is provided in the examples/custom-utop directory.