diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs
index 6d04d401a8a..90280cb1783 100644
--- a/cabal-install/src/Distribution/Client/Setup.hs
+++ b/cabal-install/src/Distribution/Client/Setup.hs
@@ -3350,7 +3350,7 @@ optionSolver get set =
   option
     []
     ["solver"]
-    ("Select dependency solver to use (default: " ++ prettyShow defaultSolver ++ "). Choices: " ++ allSolvers ++ ".")
+    ("[DEPRECATED] Select dependency solver to use (default: " ++ prettyShow defaultSolver ++ "). Choices: " ++ allSolvers ++ ".")
     get
     set
     ( reqArg
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 88803232bf6..5e40f706257 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -466,7 +466,7 @@ builds with ``cabal build`` are performed with the compiler
 
 -  Any flag accepted by ``cabal configure`` beyond
    ``./Setup configure``, namely ``--cabal-lib-version``,
-   ``--constraint``, ``--preference`` and ``--solver.``
+   ``--constraint`` and ``--preference``.
 
 -  Any flag accepted by ``cabal install`` beyond ``./Setup configure``.
 
diff --git a/doc/cabal-project.rst b/doc/cabal-project.rst
index 90f819a529c..0c563275b80 100644
--- a/doc/cabal-project.rst
+++ b/doc/cabal-project.rst
@@ -1684,6 +1684,10 @@ Most users generally won't need these.
 
     The command line variant of this field is ``--solver=modular``.
 
+    .. warning::
+
+    This CLI option has been deprecated and will be removed in a future release.
+
 .. cfg-field:: max-backjumps: nat
                --max-backjumps=N
     :synopsis: Maximum number of solver backjumps.