diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst
index 5bcea693383..2a08f5a8321 100644
--- a/configuration/override_dir_structure.rst
+++ b/configuration/override_dir_structure.rst
@@ -168,7 +168,7 @@ You also need to change the ``extra.symfony-web-dir`` option in the
 
     .. code-block:: terminal
 
-        $ php bin/console cache:clear --env=prod
+        $ php bin/console cache:clear --no-warmup --env=prod
         $ php bin/console assetic:dump --env=prod --no-debug
 
 Override the ``vendor`` Directory
diff --git a/console/usage.rst b/console/usage.rst
index c6a9e653ce8..38b745b1276 100644
--- a/console/usage.rst
+++ b/console/usage.rst
@@ -8,22 +8,19 @@ The :doc:`/components/console/usage` page of the components documentation looks
 at the global console options. When you use the console as part of the full-stack
 framework, some additional global options are available as well.
 
-By default, console commands run in the ``dev`` environment and you may want
-to change this for some commands. For example, you may want to run some commands
-in the ``prod`` environment for performance reasons. Also, the result of some commands
-will be different depending on the environment. For example, the ``cache:clear``
-command will clear and warm the cache for the specified environment only. To
-clear and warm the ``prod`` cache you need to run:
+By default, console commands run in the ``dev`` environment and you may want to
+change this for some commands. For example, you may want to run some commands in
+the ``prod`` environment for performance reasons. Also, the result of some
+commands will be different depending on the environment. For example, the
+``cache:clear`` command will clear the cache for the specified environment only.
+To clear the ``prod`` cache you need to run:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod
+    $ php bin/console cache:clear --no-warmup --env=prod
 
-or the equivalent:
-
-.. code-block:: terminal
-
-    $ php bin/console cache:clear -e prod
+    # this is equivalent:
+    $ php bin/console cache:clear --no-warmup -e prod
 
 In addition to changing the environment, you can also choose to disable debug mode.
 This can be useful where you want to run commands in the ``dev`` environment
diff --git a/deployment.rst b/deployment.rst
index f5d1b74cea0..9f8cd694bdc 100644
--- a/deployment.rst
+++ b/deployment.rst
@@ -153,11 +153,12 @@ as you normally do:
 D) Clear your Symfony Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Make sure you clear (and warm-up) your Symfony cache:
+Make sure you clear and warm-up your Symfony cache:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod --no-debug
+    $ php bin/console cache:clear --env=prod --no-debug --no-warmup
+    $ php bin/console cache:warmup --env=prod
 
 E) Dump your Assetic Assets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
index ab78b836b2c..c7fe00de8c7 100644
--- a/reference/dic_tags.rst
+++ b/reference/dic_tags.rst
@@ -504,6 +504,12 @@ process
 Cache warming occurs whenever you run the ``cache:warmup`` or ``cache:clear``
 command (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run
 when handling the request, if it wasn't done by one of the commands yet.
+
+.. versionadded:: 3.3
+    Starting from Symfony 3.3, the warm-up part of the ``cache:clear`` command
+    is deprecated. You must always pass the ``--no-warmup`` option to
+    ``cache:clear`` and use ``cache:warmup`` instead to warm-up the cache.
+
 The purpose is to initialize any cache that will be needed by the application
 and prevent the first user from any significant "cache hit" where the cache
 is generated dynamically.