diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs
index e752b573aad..08ce22a5c56 100644
--- a/cabal-install/src/Distribution/Client/Setup.hs
+++ b/cabal-install/src/Distribution/Client/Setup.hs
@@ -235,6 +235,9 @@ import System.FilePath
   ( (</>)
   )
 
+import System.IO (hPutStrLn, stderr)
+import System.IO.Unsafe (unsafePerformIO)
+
 globalCommand :: [Command action] -> CommandUI GlobalFlags
 globalCommand commands =
   CommandUI
@@ -928,7 +931,13 @@ configureExOptions _showOrParseArgs src =
           )
           (map prettyShow)
       )
-  , optionSolver configSolver (\v flags -> flags{configSolver = v})
+  , optionSolver
+      configSolver
+      ( \_ flags ->
+          unsafePerformIO $ do
+            hPutStrLn stderr "[WARNING] The --solver flag is deprecated and will be removed in a future release."
+            return flags
+      )
   , option
       []
       ["allow-older"]
@@ -3422,7 +3431,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 5419186f73c..216cb30ee47 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -499,7 +499,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-description-file.rst b/doc/cabal-project-description-file.rst
index baac75e06f9..ad0c582594e 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -1692,6 +1692,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.