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 (or Podman) 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 (or Podman) 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

Image variants

Image	Switches	Size	Codespaces
ocaml-devcontainer	ocaml	~4.5 GB	Yes
ocaml-devcontainer-rocq	ocaml	~5.5 GB	Yes
ocaml-devcontainer-tsan	ocaml, ocaml+tsan	~7.5 GB	No
oxcaml-devcontainer	oxcaml	~18.8 GB	Yes

The default image (ocaml-devcontainer) ships a single ocaml switch. See the Rocq variant, TSan variant, and OxCaml variant sections below for the other images.

Installed tools

Category	Tools
Compilers	OCaml 5.4.0
Build & dev	dune, ocaml-lsp-server, merlin, utop
Testing	alcotest, ppx_inline_test, ppx_expect, qcheck
Profiling	landmarks, memtrace, runtime_events_tools (olly), printbox
Libraries	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
utop                 # Interactive REPL

Using this devcontainer in your project

Want contributors to your OCaml project to get a working environment with one click? Add a .devcontainer/devcontainer.json that references the pre-built image.

Full guide

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)

Rocq variant

The Rocq variant adds Rocq (formerly Coq) on top of the standard OCaml image. Same ocaml switch, same tools, plus the Rocq proof assistant.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-rocq/devcontainer.json

# Local build
docker build -t ocaml-devcontainer-base base/
docker build -t ocaml-devcontainer dev/
docker build -t ocaml-devcontainer-rocq rocq/
devcontainer up --workspace-folder . --config .devcontainer-rocq-from-scratch/devcontainer.json

TSan variant

The TSan variant adds an ocaml+tsan switch for ThreadSanitizer race detection. It requires vm.mmap_rnd_bits <= 28 at runtime — use it for local development or CI, not Codespaces.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-tsan/devcontainer.json

# Switch to TSan
opam switch ocaml+tsan
eval $(opam env)

# Local build
docker build -t ocaml-devcontainer-base base/
docker build -t ocaml-devcontainer dev/
sudo sysctl -w vm.mmap_rnd_bits=28
docker build -t ocaml-devcontainer-tsan tsan/
devcontainer up --workspace-folder . --config .devcontainer-tsan-from-scratch/devcontainer.json

OxCaml variant

An OxCaml variant is available with Jane Street's OxCaml compiler. It has a single oxcaml switch with OxCaml 5.2.0+ox — supports local_ allocations and other OxCaml features. The switch includes await and parallel packages from the oxcaml opam repository.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-oxcaml/devcontainer.json

# Local build
docker build -t oxcaml-devcontainer-base oxcaml-base/
docker build -t oxcaml-devcontainer --build-arg BASE_IMAGE=oxcaml-devcontainer-base oxcaml-dev/
devcontainer up --workspace-folder . --config .devcontainer-oxcaml-from-scratch/devcontainer.json

Hacking

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