OCaml DevContainer

A ready-to-use OCaml 5.4 development environment packaged as a devcontainer. Designed for tutorials and workshops where zero-friction onboarding is critical — participants get a working environment in minutes, regardless of their OS or editor.

Choose your workflow

VS Code

This is for you if:

• You use VS Code as your primary editor
• You want graphical IDE features (hover types, diagnostics, go-to-definition)
• You have Docker installed locally

git clone https://github.com/tarides/ocaml-devcontainer.git
code ocaml-devcontainer
# Click "Reopen in Container" when prompted

Full guide

DevContainer CLI

This is for you if:

• You prefer Vim, Emacs, Neovim, or another terminal editor
• You want to use Claude Code inside the container
• You have Docker and Node.js installed locally

npm install -g @devcontainers/cli
git clone https://github.com/tarides/ocaml-devcontainer.git
cd ocaml-devcontainer
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . vim examples/hello/hello.ml

Full guide

GitHub Codespaces

This is for you if:

• You don't want to install anything on your machine
• You want the fastest possible start (~2 minutes)
• You're attending a workshop or tutorial

Click "Create a GitHub Codespace" above, or:

gh codespace create --repo tarides/ocaml-devcontainer
gh codespace ssh

Full guide

What's inside

OCaml switches

Two switches are pre-configured with identical tools:

Switch	Description
5.4.0	Standard OCaml 5.4 (default)
5.4.0+tsan	ThreadSanitizer for race detection

Switch between them:

opam switch 5.4.0+tsan
eval $(opam env)

Note: The TSan switch requires reduced ASLR entropy on the host:

sudo sysctl -w vm.mmap_rnd_bits=28

Without this, TSan binaries crash with "unexpected memory mapping" errors. See google/sanitizers#1716.

Installed tools

Category	Tools
Compilers	OCaml 5.4.0, OCaml 5.4.0+tsan
Build & dev	dune, ocaml-lsp-server, merlin, ocamlformat, utop, odoc
Testing	alcotest, ppx_inline_test, ppx_expect, qcheck
Profiling	landmarks, memtrace, runtime_events_tools (olly), printbox
Libraries	core, base
Debugging	gdb, lldb, valgrind, rr, perf, strace, ltrace, bpftrace, hyperfine
Editors	vim, emacs

Common commands

dune build           # Build the project
dune test            # Run tests
dune fmt             # Format code (ocamlformat)
utop                 # Interactive REPL
odoc                 # Generate documentation

For tutorial and workshop authors

This environment is designed to be extended. Create a tutorial-specific image layered on top:

FROM ghcr.io/tarides/ocaml-devcontainer:latest
RUN opam install -y lwt eio        # Add your packages
COPY exercises/ /home/vscode/exercises/

Tips:

• Test beforehand — spin up a Codespace and run through your exercises
• Provide a Codespace link — attendees click one button to get started
• Have a local fallback — some venues have poor wifi; the DevContainer CLI workflow works offline once images are pulled
• Clean up after — remind attendees to delete their Codespaces to avoid charges (gh codespace delete --all)

Hacking

See HACKING.md for building images, running tests, and CI details.