- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Modules, Structure & Tooling
- Files as Modules
On this page
Files as Modules, and Multi-File Project Organization
Published on August 3, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
Every .ml file in an OCaml project is automatically a module, with no declaration required to make it one. This single fact is the entire foundation of how OCaml projects scale from a single file to hundreds of them: splitting code across files is, at the same time, splitting code across modules, and everything already known about referring to a module's contents applies directly to referring to another file's contents.
A File Becomes a Module, Automatically
A file named counter.ml compiles into a module named Counter. The mapping is mechanical: take the filename, drop the .ml extension, and capitalize the first letter — module names in OCaml are always capitalized, even when the file itself uses a lowercase name.
(* counter.ml *)
let touch count = count + 1
let empty = 0
Nothing inside counter.ml declares "this is a module called Counter" — the file itself is the entire module definition, and its name comes purely from the filename on disk.
Referring to Another File's Definitions
Once a second file exists in the same project, its definitions are reached exactly the way any other module's contents are: with the module name, a dot, and the identifier being referenced.
(* main.ml *)
let () =
let total = Counter.touch Counter.empty in
Printf.printf "%d\n" total
Counter.touch and Counter.empty refer directly to the definitions inside counter.ml, with no explicit import, include, or require statement needed anywhere — Dune already knows both files are part of the same project, discovers the dependency between them by seeing Counter referenced inside main.ml, and compiles counter.ml first automatically.
open: Dropping the Qualification
Writing Counter. before every single reference gets repetitive once a module is used heavily. The open statement brings a module's contents directly into scope, letting them be referenced unqualified:
open Counter
let () =
let total = touch empty in
Printf.printf "%d\n" total
open is a genuine trade-off, not a pure convenience: the fewer qualifications a piece of code needs, the harder it becomes to tell, at a glance, which module a given identifier actually came from, especially once several modules are opened in the same file. A common middle ground is a local open, which restricts the effect of open to a single expression rather than an entire file:
let total = Counter.(touch empty)
Here, Counter.( ... ) opens Counter only for the duration of the parenthesized expression, giving the readability benefit of an unqualified reference without affecting how any other part of the file is read.
Organizing a Project Across Directories
A Dune project conventionally separates its files by role rather than mixing everything into one directory: executable entry points live under bin/, reusable library code lives under lib/, and tests live under test/. Each of these directories has its own dune file declaring what kind of component it builds — an executable, a library, or a test — and Dune treats every .ml file inside a given directory as automatically belonging to that directory's component.
As a project's lib/ directory grows past one or two files, splitting related functionality into its own file (and therefore its own module) becomes the natural way to keep any single file from growing unmanageably large. A small library implementing a data structure and a set of operations on it might reasonably split into types.ml, operations.ml, and pretty_print.ml, rather than combining everything into a single sprawling file, purely because each file corresponds to a cleanly separable concern.
How a Library Wraps Its Modules
A detail worth understanding once a library contains more than one file: by default, Dune wraps every module inside a library under a single top-level module, named after the library itself. If a library named shapes contains circle.ml and square.ml, code outside that library accesses them as Shapes.Circle and Shapes.Square, not as plain Circle and Square — the library's own name becomes an additional qualifying layer wrapped around every module it contains.
Inside the library itself, this wrapping is transparent: circle.ml and square.ml can still refer to each other directly as Circle and Square, without the Shapes. prefix, since Dune only adds that wrapping layer at the point where the library is consumed from outside. This is what allows a library's internal file organization to be restructured freely — splitting one file into two, or merging two into one — without changing how any external consumer of the library refers to it, as long as the externally visible names stay the same.
Why Cyclic File Dependencies Aren't Allowed
Two files cannot depend on each other directly: if a.ml references something from b.ml, then b.ml cannot also reference something from a.ml, since there would be no valid order left in which to compile the two of them. Dune detects this situation and reports it clearly as a dependency cycle rather than allowing the build to proceed in some arbitrary or inconsistent order. Running into this is usually a sign that a piece of shared functionality needs to be factored out into a third file that both of the original files can depend on instead, rather than depending on each other directly.
Key Takeaways
- Every
.mlfile automatically becomes a module named after the file, capitalized, with no explicit declaration required. - Cross-file references use the same
Module.identifiersyntax used for any other module, and Dune determines build order automatically from these references. openbrings a module's contents into scope unqualified; using it sparingly, or restricting it to a local open, keeps it clear where an identifier actually came from.- Conventional project layout separates files by role —
bin/,lib/,test/— and splitting a growinglib/directory into focused files is the standard way to keep individual files manageable. - By default, Dune wraps every module in a library under a single top-level module named after the library, which is what external code actually sees, even though the library's own internal files can refer to each other without that extra layer.
- Two files can never depend on each other directly; a dependency cycle between files is always a build error, typically resolved by factoring the shared logic into a separate file both can depend on.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Modules, Structure & Tooling
Next
Module Signatures
- A File Becomes a Module, Automatically
- Referring to Another File's Definitions
- open: Dropping the Qualification
- Organizing a Project Across Directories
- How a Library Wraps Its Modules
- Why Cyclic File Dependencies Aren't Allowed
- Key Takeaways
