ocaml · gridbugs · Oct 29, 2025 · Leonidas-from-XIV · Oct 29, 2025
diff --git a/bin/common.ml b/bin/common.ml
@@ -246,7 +246,7 @@ module Options_implied_by_dash_p = struct
         & opt_all ~vopt:true bool [ false ]
         & info [ "require-dune-project-file" ] ~docs ~doc)
     and+ ignore_lock_dir =
-      let doc = "Ignore dune.lock/ directory." in
+      let doc = "Ignore .dune-solution-cache/ directory." in
       Arg.(value & flag & info [ "ignore-lock-dir" ] ~docs ~doc)
     in
     { root

diff --git a/bin/pkg/outdated.ml b/bin/pkg/outdated.ml
@@ -93,7 +93,7 @@ let info =
     ; `P "For example:"
     ; `Pre "    \\$ dune pkg outdated"
     ; `Noblank
-    ; `Pre "    1/2 packages in dune.lock are outdated."
+    ; `Pre "    1/2 packages in .dune-solution-cache are outdated."
     ; `Noblank
     ; `Pre "    - ocaml 4.14.1 < 5.1.0"
     ; `Noblank

diff --git a/bin/pkg/pkg_common.ml b/bin/pkg/pkg_common.ml
@@ -181,7 +181,8 @@ module Lock_dirs_arg = struct
                []
                ~docv:"LOCKDIRS"
                ~doc:
-                 "Lock directories to check for outdated packages. Defaults to dune.lock.")
+                 "Lock directories to check for outdated packages. Defaults to \
+                  .dune-solution-cache.")
        in
        Selected (List.map arg ~f:Path.Source.of_string))
       (let+ _all =

diff --git a/doc/explanation/package-management.md b/doc/explanation/package-management.md
@@ -101,7 +101,7 @@ archives to download (since there is no central location for all archives), the
 build instructions (since each package can use its own way of building), and
 additional metadata like the system packages it depends upon.
 
-The information is stored in a directory (`dune.lock` by default) as separate
+The information is stored in a directory (`.dune-solution-cache` by default) as separate
 files, to reduce potential merge conflicts and simplify code review. Storing
 additional files like patches is also simpler this way.
 

diff --git a/doc/reference/dune-workspace/context.rst b/doc/reference/dune-workspace/context.rst
@@ -17,7 +17,7 @@ the description of an opam switch, as follows:
 
 -  ``(lock_dir <path>)`` specifies the lock directory that will be used for
    building this context (if any). If no lock directory is specified
-   ``dune.lock`` will be used. See the
+   ``.dune-solution-cache`` will be used. See the
    :doc:`/reference/dune-workspace/lock_dir` stanza for lock directory
    configuration options.
 

diff --git a/doc/reference/dune-workspace/lock_dir.rst b/doc/reference/dune-workspace/lock_dir.rst
@@ -19,7 +19,7 @@ changed if desired.
    .. describe:: (path <string>)
 
       The location in the source tree where the lock directory will be
-      created or read from. If not specified defaults to ``dune.lock``.
+      created or read from. If not specified defaults to ``.dune-solution-cache``.
 
    .. describe:: (repositories <name list>)
 

diff --git a/doc/tutorials/dune-package-management/dependencies.md b/doc/tutorials/dune-package-management/dependencies.md
@@ -26,7 +26,7 @@ to update our lock directory with the new packages.
 
 ```
 $ dune pkg lock
-Solution for dune.lock:
+Solution for .dune-solution-cache:
 - base-unix.base
 - fmt.0.9.0
 - ocaml.5.2.0
@@ -112,7 +112,7 @@ package is locked:
 
 ```
 $ dune pkg lock
-Solution for dune.lock:
+Solution for .dune-solution-cache:
 - base-unix.base
 - fmt.0.9.0
 - ocaml.5.2.0

diff --git a/doc/tutorials/dune-package-management/pinning.md b/doc/tutorials/dune-package-management/pinning.md
@@ -31,7 +31,7 @@ the information from the selected package repositories.
 
 ```
 $ dune pkg lock
-Solution for dune.lock:
+Solution for .dune-solution-cache:
 - base-unix.base
 - fmt.dev
 - ocaml.5.0.0

diff --git a/doc/tutorials/dune-package-management/repos.md b/doc/tutorials/dune-package-management/repos.md
@@ -35,7 +35,7 @@ dependencies changes accordingly:
 
 ```
 $ dune pkg lock
-Solution for dune.lock:
+Solution for .dune-solution-cache:
 - base-unix.base
 - fmt.0.9.0
 - ocaml.5.0.0

diff --git a/doc/tutorials/dune-package-management/setup.md b/doc/tutorials/dune-package-management/setup.md
@@ -63,7 +63,7 @@ This is easily done with a new Dune command:
 
 ```
 $ dune pkg lock
-Solution for dune.lock:
+Solution for .dune-solution-cache:
 - ocaml.5.2.0
 - ocaml-base-compiler.5.2.0
 - ocaml-config.3

diff --git a/src/dune_rules/clflags.mli b/src/dune_rules/clflags.mli
@@ -19,7 +19,7 @@ val debug_artifact_substitution : bool ref
 (** Print package output when building with package management *)
 val debug_package_logs : bool ref
 
-(** Whether we are ignoring "dune.lock/". *)
+(** Whether we are ignoring ".dune-solution-cache/". *)
 val ignore_lock_dir : bool ref
 
 val concurrency : int ref
diff --git a/src/dune_rules/lock_dir.ml b/src/dune_rules/lock_dir.ml
@@ -131,7 +131,7 @@ let select_lock_dir lock_dir_selection =
   Workspace.Lock_dir_selection.eval lock_dir_selection ~dir:workspace.dir ~f:expander
 ;;
 
-let default_dir = "dune.lock"
+let default_dir = ".dune-solution-cache"
 
 (* location where project lock dirs are stored *)
 let path_prefix =
@@ -148,7 +148,7 @@ let dev_tool_to_path_segment dev_tool =
 ;;
 
 let dev_tool_source_lock_dir dev_tool =
-  let dev_tools_path = Path.Source.(relative root "dev-tools.locks") in
+  let dev_tools_path = Path.Source.(relative root ".dune-tools-solution-cache") in
   let dev_tool_segment = dev_tool_to_path_segment dev_tool in
   Path.Source.append_local dev_tools_path dev_tool_segment
 ;;

diff --git a/src/dune_rules/pkg_rules.ml b/src/dune_rules/pkg_rules.ml
@@ -1534,7 +1534,7 @@ end = struct
               [ "dir", Path.External.to_dyn e ]
           | In_source_tree s ->
             (match Path.Source.explode s with
-             | [ "dev-tools.locks"; dev_tool; files_dir ] ->
+             | [ ".dune-tools-solution-cache"; dev_tool; files_dir ] ->
                Path.Build.L.relative
                  Private_context.t.build_dir
                  [ "default"; ".dev-tool-locks"; dev_tool; files_dir ]

diff --git a/src/source/workspace.ml b/src/source/workspace.ml
@@ -131,7 +131,7 @@ module Lock_dir = struct
     let decode =
       let+ loc = loc
       and+ path =
-        let+ path = field ~default:"dune.lock" "path" string in
+        let+ path = field ~default:".dune-solution-cache" "path" string in
         Path.Source.relative dir path
       and+ solver_env = field_o "solver_env" Solver_env.decode
       and+ unset_solver_vars =

diff --git a/test/blackbox-tests/test-cases/describe/describe_location.t b/test/blackbox-tests/test-cases/describe/describe_location.t
@@ -26,7 +26,7 @@ An executable from the current project:
 
 Test that executables from dependencies are located correctly:
 
-  $ source_lock_dir="dune.lock"
+  $ source_lock_dir=".dune-solution-cache"
   $ mkdir -p "${source_lock_dir}"
   $ cat > "${source_lock_dir}"/lock.dune <<EOF
   > (lang package 0.1)

diff --git a/test/blackbox-tests/test-cases/pkg/additional-constraints-ocaml-system.t b/test/blackbox-tests/test-cases/pkg/additional-constraints-ocaml-system.t
@@ -35,7 +35,7 @@ A package that depends on ocaml:
 Try solving without additional constraints:
   $ add_mock_repo_if_needed
   $ dune pkg lock
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - ocaml.0.0.1
   - ocaml-base-compiler.0.0.1
 
@@ -52,6 +52,6 @@ Now make a workspace file adding the constarint on ocaml-system:
 
 Solve again. This time ocaml-system is chosen.
   $ dune pkg lock
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - ocaml.0.0.1
   - ocaml-system.0.0.1
diff --git a/test/blackbox-tests/test-cases/pkg/additional-constraints.t b/test/blackbox-tests/test-cases/pkg/additional-constraints.t
@@ -27,7 +27,7 @@ Notice that the constraints field doesn't introduce additional packages. The
   >  (name x)
   >  (depends foo bar))
   > EOF
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - bar.1.0.0
   - foo.1.0.0
 
@@ -52,7 +52,7 @@ There are no valid version of foo at the moment:
   >  (depends foo bar))
   > EOF
   Error: Unable to solve dependencies for the following lock directories:
-  Lock directory dune.lock:
+  Lock directory .dune-solution-cache:
   Couldn't solve the package dependency formula.
   Selected candidates: bar.1.9.1 x.dev
   - foo -> (problem)
@@ -70,6 +70,6 @@ If we add one:
   >  (name x)
   >  (depends foo bar))
   > EOF
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - bar.1.9.1
   - foo.0.9.0
diff --git a/test/blackbox-tests/test-cases/pkg/build-package-logs.t b/test/blackbox-tests/test-cases/pkg/build-package-logs.t
@@ -22,7 +22,7 @@ Create a package with a failing command that throws an error:
 Building the package should fail and print an error:
 
   $ build_pkg x 2>&1 | sed -E 's#/.*/cat#cat#g'
-  File "dune.lock/x.pkg", line 4, characters 11-14:
+  File ".dune-solution-cache/x.pkg", line 4, characters 11-14:
   4 |       (run cat i_dont_exist)))
                  ^^^
   Error: Logs for package x

diff --git a/test/blackbox-tests/test-cases/pkg/check-dependency-hash.t b/test/blackbox-tests/test-cases/pkg/check-dependency-hash.t
@@ -13,7 +13,7 @@ Start with a project with a single package with no dependencies:
   > (package
   >  (name foo))
   > EOF
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   (no dependencies to lock)
   $ cat ${default_lock_dir}/lock.dune
   (lang package 0.1)
@@ -31,13 +31,13 @@ Add a dependency to the project:
   >  (depends a))
   > EOF
   $ dune pkg validate-lockdir
-  Lockdir dune.lock does not contain a solution for local packages:
+  Lockdir .dune-solution-cache does not contain a solution for local packages:
   Error: This project has at least one non-local dependency but the lockdir
   doesn't contain a dependency hash.
   An example of a non-local dependency of this project is: a
   Hint: Regenerate the lockdir by running 'dune pkg lock'
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
 
 Add a non-local dependency to the package:
@@ -47,7 +47,7 @@ Add a non-local dependency to the package:
   >  (name foo)
   >  (depends a))
   > EOF
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - a.0.0.1
   $ cat ${default_lock_dir}/lock.dune
   (lang package 0.1)
@@ -67,8 +67,8 @@ Add a second dependency to the project:
   >  (depends a b))
   > EOF
   $ dune pkg validate-lockdir
-  Lockdir dune.lock does not contain a solution for local packages:
-  File "dune.lock/lock.dune", line 3, characters 17-49:
+  Lockdir .dune-solution-cache does not contain a solution for local packages:
+  File ".dune-solution-cache/lock.dune", line 3, characters 17-49:
   Error: Dependency hash in lockdir does not match the hash of non-local
   dependencies of this project. The lockdir expects the the non-local
   dependencies to hash to:
@@ -77,7 +77,7 @@ Add a second dependency to the project:
   d18946fdd9833ae312d309f654f11c1b
   Hint: Regenerate the lockdir by running 'dune pkg lock'
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
 
 Remove all dependencies from the project:
@@ -87,13 +87,13 @@ Remove all dependencies from the project:
   >  (name foo))
   > EOF
   $ dune pkg validate-lockdir
-  Lockdir dune.lock does not contain a solution for local packages:
-  File "dune.lock/lock.dune", line 3, characters 17-49:
+  Lockdir .dune-solution-cache does not contain a solution for local packages:
+  File ".dune-solution-cache/lock.dune", line 3, characters 17-49:
   Error: This project has no non-local dependencies yet the lockfile contains a
   dependency hash: 7ba1cacd46bb2609d7b9735909c3b8a5
   Hint: Regenerate the lockdir by running 'dune pkg lock'
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
 
 Exercise handling invalid dependency hashes.
@@ -110,32 +110,32 @@ Exercise handling invalid dependency hashes.
 Case where the label ("md5") is missing:
   $ make_lock_metadata_with_hash badhash
   $ dune pkg validate-lockdir
-  Failed to parse lockdir dune.lock:
-  File "dune.lock/lock.dune", line 2, characters 17-24:
+  Failed to parse lockdir .dune-solution-cache:
+  File ".dune-solution-cache/lock.dune", line 2, characters 17-24:
   Error: Dependency hash is not a valid md5 hash: badhash
 
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
 
 Case where the label is not "md5":
   $ make_lock_metadata_with_hash foo=badhash
   $ dune pkg validate-lockdir
-  Failed to parse lockdir dune.lock:
-  File "dune.lock/lock.dune", line 2, characters 17-28:
+  Failed to parse lockdir .dune-solution-cache:
+  File ".dune-solution-cache/lock.dune", line 2, characters 17-28:
   Error: Dependency hash is not a valid md5 hash: foo=badhash
 
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
 
 Case where the the hash is not a valid md5 hash:
   $ make_lock_metadata_with_hash md5=badhash
   $ dune pkg validate-lockdir
-  Failed to parse lockdir dune.lock:
-  File "dune.lock/lock.dune", line 2, characters 17-28:
+  Failed to parse lockdir .dune-solution-cache:
+  File ".dune-solution-cache/lock.dune", line 2, characters 17-28:
   Error: Dependency hash is not a valid md5 hash: md5=badhash
 
   Error: Some lockdirs do not contain solutions for local packages:
-  - dune.lock
+  - .dune-solution-cache
   [1]
diff --git a/test/blackbox-tests/test-cases/pkg/checksum-local-archive.t b/test/blackbox-tests/test-cases/pkg/checksum-local-archive.t
@@ -15,7 +15,7 @@ Make sure that we verify archives of local archives
   > EOF
 
   $ build_pkg foo
-  File "dune.lock/foo.pkg", line 4, characters 12-48:
+  File ".dune-solution-cache/foo.pkg", line 4, characters 12-48:
   4 |   (checksum md5=069aa55d40e548280f92af693f6c625a)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   Error: Invalid checksum, got

diff --git a/test/blackbox-tests/test-cases/pkg/common-filters-deps.t b/test/blackbox-tests/test-cases/pkg/common-filters-deps.t
@@ -23,6 +23,6 @@ documentation-only deps are omitted from the solution.
 Dune will also not include dependencies marked `post` in the lock directory.
 
   $ solve "(test :with-test) (doc :with-doc) (dev-setup :with-dev-setup) (dev :with-dev) (build :build) (post :post)"
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - build.0.0.1
   - test.0.0.1
diff --git a/test/blackbox-tests/test-cases/pkg/compiler-post-dependencies.t b/test/blackbox-tests/test-cases/pkg/compiler-post-dependencies.t
@@ -7,7 +7,7 @@ Exercise dune resolving the post dependencies found in compiler packages.
   > (lang dune 3.20)
   > (pkg enabled)
   > (lock_dir
-  >  (path dune.lock)
+  >  (path .dune-solution-cache)
   >  (repositories mock)
   >  (solver_env
   >   (os linux)))
@@ -44,7 +44,7 @@ lists to prevent circular dependencies at package build time.
   > EOF
 
   $ solve ocaml-base-compiler 
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - ocaml-base-compiler.0.0.1
 
 Ensure that packages can be resolved at build time. This checks that

diff --git a/test/blackbox-tests/test-cases/pkg/compute-checksums-when-missing.t b/test/blackbox-tests/test-cases/pkg/compute-checksums-when-missing.t
@@ -21,7 +21,7 @@ A file that will comprise the package source:
   Package "foo" has source archive which lacks a checksum.
   The source archive will be downloaded from: http://0.0.0.0:1
   Dune will compute its own checksum for this source archive.
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - foo.0.0.1
 
 Replace the path in the lockfile as it would otherwise include the sandbox
@@ -52,7 +52,7 @@ Recreate the foo package with a fake port number to signal that the file will
   The source archive will be downloaded from: http://0.0.0.0:9000
   Dune will compute its own checksum for this source archive.
   Warning: Download failed with code 404
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - foo.0.0.1
   $ cat ${default_lock_dir}/foo.pkg
   (version 0.0.1)
@@ -71,7 +71,7 @@ Check that no checksum is computed for a local source file:
   > }
   > EOF
   $ solve foo 2>&1
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - foo.0.0.1
 
 Check that no checksum is computed for a local source directory:
@@ -83,7 +83,7 @@ Check that no checksum is computed for a local source directory:
   > }
   > EOF
   $ solve foo 2>&1
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - foo.0.0.1
 
 
@@ -124,7 +124,7 @@ asserted by the fact that the webserver will only serve the file a single time.
   Package "foo" has source archive which lacks a checksum.
   The source archive will be downloaded from: http://0.0.0.0:2
   Dune will compute its own checksum for this source archive.
-  Solution for dune.lock:
+  Solution for .dune-solution-cache:
   - bar.0.0.1
   - baz.0.0.1
   - foo.0.0.1