diff --git a/doc/configuration.md b/doc/configuration.md
index e6d0943d8..b5819c319 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -813,6 +813,10 @@ This setting will be ignored if no [key][key] has been provided.
 
 ## Metadata (`metadata`)
 
+!!! warning
+
+    The metadata setting has been deprecated as of Box 4.6.0. See [#1152].
+
 The metadata (`any` default none) setting can be any value. This value will be stored as metadata that can be retrieved
 from the built PHAR ([Phar::getMetadata()][phar.getmetadata]).
 
@@ -1070,3 +1074,4 @@ The short commit hash will only be used if no tag is available.
 [stub]: #stub
 [symfony-finder]: https://symfony.com/doc/current//components/finder.html
 [zlib-extension]: https://secure.php.net/manual/en/book.zlib.php
+[#1152]: https://github.com/box-project/box/issues/1152
diff --git a/src/Configuration/Configuration.php b/src/Configuration/Configuration.php
index 2495110b8..9d28de0fa 100644
--- a/src/Configuration/Configuration.php
+++ b/src/Configuration/Configuration.php
@@ -1892,6 +1892,8 @@ private static function retrieveMetadata(stdClass $raw, ConfigurationLogger $log
             return null;
         }
 
+        $logger->addWarning('Using the "metadata" setting is deprecated and will be removed in 5.0.0.');
+
         $metadata = $raw->{self::METADATA_KEY};
 
         return is_object($metadata) ? (array) $metadata : $metadata;
diff --git a/tests/Configuration/ConfigurationTest.php b/tests/Configuration/ConfigurationTest.php
index 6a290f795..811486203 100644
--- a/tests/Configuration/ConfigurationTest.php
+++ b/tests/Configuration/ConfigurationTest.php
@@ -1136,7 +1136,12 @@ public function test_can_configure_metadata(): void
         self::assertSame(123, $this->config->getMetadata());
 
         self::assertSame([], $this->config->getRecommendations());
-        self::assertSame([], $this->config->getWarnings());
+        self::assertSame(
+            [
+                'Using the "metadata" setting is deprecated and will be removed in 5.0.0.',
+            ],
+            $this->config->getWarnings(),
+        );
     }
 
     public function test_a_recommendation_is_given_if_the_default_metadata_is_provided(): void
diff --git a/tests/Console/Command/CompileTest.php b/tests/Console/Command/CompileTest.php
index 33f53ddfe..ef4fa1d21 100644
--- a/tests/Console/Command/CompileTest.php
+++ b/tests/Console/Command/CompileTest.php
@@ -281,7 +281,8 @@ public function test_it_can_build_a_phar_file(): void
             * Done.
 
             No recommendation found.
-            ⚠️  <warning>1 warning found:</warning>
+            ⚠️  <warning>2 warnings found:</warning>
+                - Using the "metadata" setting is deprecated and will be removed in 5.0.0.
                 - Using an OpenSSL signature is deprecated and will be removed in 5.0.0. Please check https://github.com/box-project/box/blob/main/doc/phar-signing.md for alternatives.
 
              // PHAR: {$numberOfFiles} files (100B)
@@ -574,7 +575,6 @@ public function test_it_can_build_a_phar_with_complete_mapping(): void
                     'map' => [
                         ['a/deep/test/directory' => 'sub'],
                     ],
-                    'metadata' => ['rand' => $rand = random_int(0, mt_getrandmax())],
                     'output' => 'test.phar',
                 ],
             ),
@@ -626,10 +626,6 @@ public function test_it_can_build_a_phar_with_complete_mapping(): void
                 > Generated by Humbug Box {$version}.
                 >
                 > @link https://github.com/humbug/box
-            ? Setting metadata
-              - array (
-              'rand' => {$rand},
-            )
             ? Dumping the Composer autoloader
             ? Removing the Composer dump artefacts
             ? No compression
@@ -685,12 +681,6 @@ public function test_it_can_build_a_phar_with_complete_mapping(): void
 
         self::assertSame($expectedStub, $actualStub);
 
-        self::assertSame(
-            ['rand' => $rand],
-            $phar->getMetadata(),
-            'Expected PHAR metadata to be set',
-        );
-
         $expectedFiles = [
             '/one/',
             '/one/test.php',
@@ -898,7 +888,8 @@ public function test_it_can_build_a_phar_file_in_verbose_mode(): void
             * Done.
 
             No recommendation found.
-            ⚠️  <warning>1 warning found:</warning>
+            ⚠️  <warning>2 warnings found:</warning>
+                - Using the "metadata" setting is deprecated and will be removed in 5.0.0.
                 - Using an OpenSSL signature is deprecated and will be removed in 5.0.0. Please check https://github.com/box-project/box/blob/main/doc/phar-signing.md for alternatives.
 
              // PHAR: {$expectedNumberOfFiles} files (100B)
@@ -1028,7 +1019,8 @@ public function test_it_can_build_a_phar_file_in_very_verbose_mode(): void
             * Done.
 
             No recommendation found.
-            ⚠️  <warning>1 warning found:</warning>
+            ⚠️  <warning>2 warnings found:</warning>
+                - Using the "metadata" setting is deprecated and will be removed in 5.0.0.
                 - Using an OpenSSL signature is deprecated and will be removed in 5.0.0. Please check https://github.com/box-project/box/blob/main/doc/phar-signing.md for alternatives.
 
              // PHAR: {$expectedNumberOfFiles} files (100B)