diff --git a/README.md b/README.md
index 1a8d2e74d..04ead0e19 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,7 @@ path = "fake_lib.rs"
 [dependencies]
 log = "=0.3.6"
 
-[raze]
+[package.metadata.raze]
 # The path relative path to the Bazel workspace root (location of
 # WORKSPACE.bazel/WORKSPACE file). If no workspace file is found,
 # the current working directory is used.
@@ -135,10 +135,10 @@ is required.
 #### Generate a Cargo.toml
 
 Generate a Cargo.toml, similar to Vendoring mode but add a new `genmode` directive in the
-`[raze]` section
+`[package.metadata.raze]` section
 
 ```toml
-[raze]
+[package.metadata.raze]
 # The path relative path to the Bazel workspace root (location of
 # WORKSPACE.bazel/WORKSPACE file). If no workspace file is found,
 # the current working directory is used.
@@ -198,7 +198,7 @@ source file. These build-scripts rules can actually be executed and used within
 Bazel by including a directive in your Cargo.toml prior to generation:
 
 ```toml
-[raze.crates.clang-sys.'0.21.1']
+[package.metadata.raze.crates.clang-sys.'0.21.1']
 gen_buildrs = true
 ```
 
@@ -214,7 +214,7 @@ compilation target is statically known), they can be provided from within the
 Cargo.toml, in the following manner
 
 ```toml
-[raze.crates.unicase.'2.1.0']
+[package.metadata.raze.crates.unicase.'2.1.0']
 additional_flags = [
   # Rustc is 1.15, enable all optional settings
   "--cfg=__unicase__iter_cmp",
@@ -235,7 +235,7 @@ rule for it, and add the dependency to the corresponding `-sys` crate. For
 openssl, this may in part look like:
 
 ```toml
-[raze.crates.openssl-sys.'0.9.24']
+[package.metadata.raze.crates.openssl-sys.'0.9.24']
 additional_flags = [
   # Vendored openssl is 1.0.2m
   "--cfg=ossl102",
@@ -246,7 +246,7 @@ additional_deps = [
   "@//third_party/openssl:ssl",
 ]
 
-[raze.crates.openssl.'0.10.2']
+[package.metadata.raze.crates.openssl.'0.10.2']
 additional_flags = [
   # Vendored openssl is 1.0.2m
   "--cfg=ossl102",
@@ -273,7 +273,7 @@ facilitated by removing and supplementing dependencies in the Cargo.toml,
 pre-generation:
 
 ```toml
-[raze.crates.sdl2.'0.31.0']
+[package.metadata.raze.crates.sdl2.'0.31.0']
 skipped_deps = [
   "sdl2-sys-0.31.0"
 ]
@@ -290,7 +290,7 @@ files by processing C or C++ files. A directive can be added to the Cargo.toml
 to tell Bazel to expose such binaries for you:
 
 ```toml
-[raze.crates.bindgen.'0.32.2']
+[package.metadata.raze.crates.bindgen.'0.32.2']
 gen_buildrs = true # needed to build bindgen
 extra_aliased_targets = [
   "cargo_bin_bindgen"
@@ -308,14 +308,14 @@ of your `Cargo.toml` file will not result in generated Bazel targets. Cargo-raze
 has a special field to handle these crates when using `genmode = "Remote"`:
 
 ```toml
-[raze.binary_deps]
+[package.metadata.raze.binary_deps]
 wasm-bindgen-cli = "0.2.68"
 ```
 
 In the snippet above, the `wasm-bindgen-cli` crate is defined as binary dependency
 and Cargo-raze will ensure metadata for this and any other crate defined here are
 included in the resulting output directory. Lockfiles for targets specified under
-`[raze.binary_deps]` will be generated into a `lockfiles` directory inside the path
+`[package.metadata.raze.binary_deps]` will be generated into a `lockfiles` directory inside the path
 specified by `workspace_path`.
 
 ## FAQ
@@ -394,4 +394,4 @@ See these examples of providing crate configuration:
 
 - [openssl](https://github.com/acmcarther/compile_openssl)
 
-The `[raze]` section is derived from a struct declared in [impl/src/settings.rs](./impl/src/settings.rs).
+The `[package.metadata.raze]` section is derived from a struct declared in [impl/src/settings.rs](./impl/src/settings.rs).
diff --git a/examples/remote/README.md b/examples/remote/README.md
index 774ab9514..585ad5bcf 100644
--- a/examples/remote/README.md
+++ b/examples/remote/README.md
@@ -8,6 +8,6 @@ In order to make sure that this assertion holds, please make sure set up **Cargo
 **Cargo.toml**
 ```toml
 
-[raze]
+[package.metadata.raze]
 gen_workspace_prefix = "<folder>"
 ```
\ No newline at end of file
diff --git a/examples/remote/binary_dependencies/Cargo.toml b/examples/remote/binary_dependencies/Cargo.toml
index 08e39b403..352db27a2 100644
--- a/examples/remote/binary_dependencies/Cargo.toml
+++ b/examples/remote/binary_dependencies/Cargo.toml
@@ -10,20 +10,20 @@ path = "src/main.rs"
 [dependencies]
 ferris-says = "0.2.0"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/binary_dependencies/cargo"
 gen_workspace_prefix = "remote_binary_dependencies"
 genmode = "Remote"
 default_gen_buildrs = true
 
-[raze.binary_deps]
+[package.metadata.raze.binary_deps]
 texture-synthesis-cli = "0.8.0"
 
-[raze.crates.texture-synthesis-cli.'0.8.0']
+[package.metadata.raze.crates.texture-synthesis-cli.'0.8.0']
 extra_aliased_targets = ["cargo_bin_texture_synthesis"]
 
-[raze.crates.crossbeam-utils.'0.7.2']
+[package.metadata.raze.crates.crossbeam-utils.'0.7.2']
 gen_buildrs = false
 
-[raze.crates.image.'0.23.0']
+[package.metadata.raze.crates.image.'0.23.0']
 data_attr = "[\"README.md\"]"
diff --git a/examples/remote/complicated_cargo_library/Cargo.toml b/examples/remote/complicated_cargo_library/Cargo.toml
index 9a264697a..d34f01970 100644
--- a/examples/remote/complicated_cargo_library/Cargo.toml
+++ b/examples/remote/complicated_cargo_library/Cargo.toml
@@ -14,24 +14,24 @@ regex = "=0.2.5"
 specs = "=0.10.0"
 security-framework-sys = "=0.2.2"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/complicated_cargo_library/cargo"
 gen_workspace_prefix = "remote_complicated_cargo_library"
 genmode = "Remote"
 
-[raze.crates.proc-macro2.'0.4.30']
+[package.metadata.raze.crates.proc-macro2.'0.4.30']
 additional_flags = [
     "--cfg=use_proc_macro",
 ]
 
-[raze.crates.syn.'0.15.44']
+[package.metadata.raze.crates.syn.'0.15.44']
 gen_buildrs = true
 
-[raze.crates.libloading.'0.5.2']
+[package.metadata.raze.crates.libloading.'0.5.2']
 additional_deps = [":global_static"]
 additional_build_file = "cargo/libloading_global_static.BUILD"
 
-[raze.crates.regex.'0.2.5']
+[package.metadata.raze.crates.regex.'0.2.5']
 skipped_deps = [
   # This will break the regex crate
   #"regex-syntax-0.4.2"
diff --git a/examples/remote/no_deps/Cargo.toml b/examples/remote/no_deps/Cargo.toml
index 6ac869b68..a804c42fd 100644
--- a/examples/remote/no_deps/Cargo.toml
+++ b/examples/remote/no_deps/Cargo.toml
@@ -7,7 +7,7 @@ authors = ["UebelAndre <github@uebelandre.com>"]
 name = "no_deps"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/no_deps/cargo"
 genmode = "Remote"
 gen_workspace_prefix = "remote_no_deps"
diff --git a/examples/remote/non_cratesio/Cargo.toml b/examples/remote/non_cratesio/Cargo.toml
index f1f33c29c..5946dc19b 100644
--- a/examples/remote/non_cratesio/Cargo.toml
+++ b/examples/remote/non_cratesio/Cargo.toml
@@ -15,13 +15,13 @@ log = { git = "https://github.com/rust-lang-nursery/log.git", rev = "bf40d1f563c
 name = "non_cratesio"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/non_cratesio/cargo"
 target = "x86_64-unknown-linux-gnu"
 genmode = "Remote"
 gen_workspace_prefix = "remote_non_cratesio"
 
-[raze.crates.log.'0.4.11']
+[package.metadata.raze.crates.log.'0.4.11']
 additional_flags = [
     "--cfg=atomic_cas"
 ]
diff --git a/examples/remote/non_cratesio/README.md b/examples/remote/non_cratesio/README.md
index d33aa4ee3..635052460 100644
--- a/examples/remote/non_cratesio/README.md
+++ b/examples/remote/non_cratesio/README.md
@@ -5,7 +5,7 @@
 
 1. Run `cargo install cargo-raze`
 2. Generate a Cargo.toml with desired dependencies into cargo/Cargo.toml
-3. Add a [raze] section with your desired options (see cargo-raze `settings::CargoToml` for
+3. Add a [package.metadata.raze] section with your desired options (see cargo-raze `settings::CargoToml` for
    the exact details)
 4. Run `cargo vendor --versioned-dirs` from `cargo/`
 5. Run `cargo raze` from `cargo/`
diff --git a/examples/vendored/complicated_cargo_library/Cargo.toml b/examples/vendored/complicated_cargo_library/Cargo.toml
index 3ed97aa09..a047fad8b 100644
--- a/examples/vendored/complicated_cargo_library/Cargo.toml
+++ b/examples/vendored/complicated_cargo_library/Cargo.toml
@@ -12,17 +12,17 @@ specs = "0.10.0"
 name = "complicated_cargo_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/complicated_cargo_library/cargo"
 gen_workspace_prefix = "vendored_complicated_cargo_library"
 genmode = "Vendored"
 
-[raze.crates.proc-macro2.'0.4.30']
+[package.metadata.raze.crates.proc-macro2.'0.4.30']
 additional_flags = [
     "--cfg=use_proc_macro",
 ]
 
-[raze.crates.regex.'0.2.11']
+[package.metadata.raze.crates.regex.'0.2.11']
 additional_deps = [
   # Add an unused dep
   "//vendored/complicated_cargo_library/cargo:specs"
@@ -34,5 +34,5 @@ additional_flags = [
 # Add an unused environment variable
 additional_env = { NOT_USED_KEY = "not_used_value" }
 
-[raze.crates.conduit-mime-types.'0.7.3']
+[package.metadata.raze.crates.conduit-mime-types.'0.7.3']
 data_attr = "glob([\"data/**\"])"
diff --git a/examples/vendored/hello_cargo_library/Cargo.toml b/examples/vendored/hello_cargo_library/Cargo.toml
index 0e9f8b08e..5632489e0 100644
--- a/examples/vendored/hello_cargo_library/Cargo.toml
+++ b/examples/vendored/hello_cargo_library/Cargo.toml
@@ -11,7 +11,7 @@ fern = "=0.3.5"
 name = "hello_cargo_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/hello_cargo_library/cargo"
 target = "x86_64-unknown-linux-gnu"
 output_buildfile_suffix = "BUILD.bazel"
diff --git a/examples/vendored/non_cratesio_library/Cargo.toml b/examples/vendored/non_cratesio_library/Cargo.toml
index 7523fe628..c553a6409 100644
--- a/examples/vendored/non_cratesio_library/Cargo.toml
+++ b/examples/vendored/non_cratesio_library/Cargo.toml
@@ -16,13 +16,13 @@ log = { git = "https://github.com/rust-lang-nursery/log.git", rev = "bf40d1f563c
 name = "non_cratesio_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/non_cratesio_library/cargo"
 target = "x86_64-unknown-linux-gnu"
 gen_workspace_prefix = "vendored_non_cratesio_library"
 genmode = "Vendored"
 
-[raze.crates.log.'0.4.11']
+[package.metadata.raze.crates.log.'0.4.11']
 additional_flags = [
     "--cfg=atomic_cas"
 ]
diff --git a/impl/src/settings.rs b/impl/src/settings.rs
index 8f2651801..8055e49d9 100644
--- a/impl/src/settings.rs
+++ b/impl/src/settings.rs
@@ -26,7 +26,18 @@ pub type CrateSettingsPerVersion = HashMap<Version, CrateSettings>;
  */
 #[derive(Debug, Clone, Deserialize)]
 pub struct CargoToml {
-  pub raze: RazeSettings,
+  pub raze: Option<RazeSettings>,
+  pub package: Option<PackageToml>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct PackageToml {
+  pub metadata: Option<MetadataToml>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct MetadataToml {
+  pub raze: Option<RazeSettings>,
 }
 
 /** The configuration settings for `cargo-raze`, included in Cargo.toml. */
@@ -370,7 +381,35 @@ pub fn load_settings<T: AsRef<Path>>(cargo_toml_path: T) -> Result<RazeSettings,
     return Err(RazeError::Generic(err.to_string()));
   }
   let mut settings = match toml::from_str::<CargoToml>(&toml_contents) {
-    Ok(toml) => toml.raze,
+    Ok(CargoToml {
+      package:
+        Some(PackageToml {
+          metadata: Some(MetadataToml { raze: Some(raze) }),
+        }),
+      raze: top_level_raze,
+    }) => {
+      if top_level_raze.is_some() {
+        eprintln!(
+          "WARNING: Both [raze] and [package.metadata.raze] are set. \
+            Using [package.metadata.raze] and ignoring [raze], which is deprecated."
+        );
+      }
+      raze
+    },
+    Ok(CargoToml {
+      raze: Some(raze), ..
+    }) => {
+      eprintln!(
+        "WARNING: The top-level [raze] key is deprecated. \
+          Please set [package.metadata.raze] instead."
+      );
+      raze
+    },
+    Ok(_) => {
+      return Err(RazeError::Generic(
+        "Cargo.toml has no `raze` or `package.metadata.raze` field".into(),
+      ));
+    },
     Err(err) => {
       return Err(RazeError::Generic(err.to_string()));
     },
diff --git a/smoke_test/remote/README.md b/smoke_test/remote/README.md
index 774ab9514..585ad5bcf 100644
--- a/smoke_test/remote/README.md
+++ b/smoke_test/remote/README.md
@@ -8,6 +8,6 @@ In order to make sure that this assertion holds, please make sure set up **Cargo
 **Cargo.toml**
 ```toml
 
-[raze]
+[package.metadata.raze]
 gen_workspace_prefix = "<folder>"
 ```
\ No newline at end of file
diff --git a/smoke_test/remote/binary_dependencies/Cargo.toml b/smoke_test/remote/binary_dependencies/Cargo.toml
index 08e39b403..352db27a2 100644
--- a/smoke_test/remote/binary_dependencies/Cargo.toml
+++ b/smoke_test/remote/binary_dependencies/Cargo.toml
@@ -10,20 +10,20 @@ path = "src/main.rs"
 [dependencies]
 ferris-says = "0.2.0"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/binary_dependencies/cargo"
 gen_workspace_prefix = "remote_binary_dependencies"
 genmode = "Remote"
 default_gen_buildrs = true
 
-[raze.binary_deps]
+[package.metadata.raze.binary_deps]
 texture-synthesis-cli = "0.8.0"
 
-[raze.crates.texture-synthesis-cli.'0.8.0']
+[package.metadata.raze.crates.texture-synthesis-cli.'0.8.0']
 extra_aliased_targets = ["cargo_bin_texture_synthesis"]
 
-[raze.crates.crossbeam-utils.'0.7.2']
+[package.metadata.raze.crates.crossbeam-utils.'0.7.2']
 gen_buildrs = false
 
-[raze.crates.image.'0.23.0']
+[package.metadata.raze.crates.image.'0.23.0']
 data_attr = "[\"README.md\"]"
diff --git a/smoke_test/remote/complicated_cargo_library/Cargo.toml b/smoke_test/remote/complicated_cargo_library/Cargo.toml
index 9a264697a..d34f01970 100644
--- a/smoke_test/remote/complicated_cargo_library/Cargo.toml
+++ b/smoke_test/remote/complicated_cargo_library/Cargo.toml
@@ -14,24 +14,24 @@ regex = "=0.2.5"
 specs = "=0.10.0"
 security-framework-sys = "=0.2.2"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/complicated_cargo_library/cargo"
 gen_workspace_prefix = "remote_complicated_cargo_library"
 genmode = "Remote"
 
-[raze.crates.proc-macro2.'0.4.30']
+[package.metadata.raze.crates.proc-macro2.'0.4.30']
 additional_flags = [
     "--cfg=use_proc_macro",
 ]
 
-[raze.crates.syn.'0.15.44']
+[package.metadata.raze.crates.syn.'0.15.44']
 gen_buildrs = true
 
-[raze.crates.libloading.'0.5.2']
+[package.metadata.raze.crates.libloading.'0.5.2']
 additional_deps = [":global_static"]
 additional_build_file = "cargo/libloading_global_static.BUILD"
 
-[raze.crates.regex.'0.2.5']
+[package.metadata.raze.crates.regex.'0.2.5']
 skipped_deps = [
   # This will break the regex crate
   #"regex-syntax-0.4.2"
diff --git a/smoke_test/remote/no_deps/Cargo.toml b/smoke_test/remote/no_deps/Cargo.toml
index 6ac869b68..a804c42fd 100644
--- a/smoke_test/remote/no_deps/Cargo.toml
+++ b/smoke_test/remote/no_deps/Cargo.toml
@@ -7,7 +7,7 @@ authors = ["UebelAndre <github@uebelandre.com>"]
 name = "no_deps"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/no_deps/cargo"
 genmode = "Remote"
 gen_workspace_prefix = "remote_no_deps"
diff --git a/smoke_test/remote/non_cratesio/Cargo.toml b/smoke_test/remote/non_cratesio/Cargo.toml
index f1f33c29c..5946dc19b 100644
--- a/smoke_test/remote/non_cratesio/Cargo.toml
+++ b/smoke_test/remote/non_cratesio/Cargo.toml
@@ -15,13 +15,13 @@ log = { git = "https://github.com/rust-lang-nursery/log.git", rev = "bf40d1f563c
 name = "non_cratesio"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//remote/non_cratesio/cargo"
 target = "x86_64-unknown-linux-gnu"
 genmode = "Remote"
 gen_workspace_prefix = "remote_non_cratesio"
 
-[raze.crates.log.'0.4.11']
+[package.metadata.raze.crates.log.'0.4.11']
 additional_flags = [
     "--cfg=atomic_cas"
 ]
diff --git a/smoke_test/remote/non_cratesio/README.md b/smoke_test/remote/non_cratesio/README.md
index d33aa4ee3..635052460 100644
--- a/smoke_test/remote/non_cratesio/README.md
+++ b/smoke_test/remote/non_cratesio/README.md
@@ -5,7 +5,7 @@
 
 1. Run `cargo install cargo-raze`
 2. Generate a Cargo.toml with desired dependencies into cargo/Cargo.toml
-3. Add a [raze] section with your desired options (see cargo-raze `settings::CargoToml` for
+3. Add a [package.metadata.raze] section with your desired options (see cargo-raze `settings::CargoToml` for
    the exact details)
 4. Run `cargo vendor --versioned-dirs` from `cargo/`
 5. Run `cargo raze` from `cargo/`
diff --git a/smoke_test/vendored/complicated_cargo_library/Cargo.toml b/smoke_test/vendored/complicated_cargo_library/Cargo.toml
index 3ed97aa09..a047fad8b 100644
--- a/smoke_test/vendored/complicated_cargo_library/Cargo.toml
+++ b/smoke_test/vendored/complicated_cargo_library/Cargo.toml
@@ -12,17 +12,17 @@ specs = "0.10.0"
 name = "complicated_cargo_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/complicated_cargo_library/cargo"
 gen_workspace_prefix = "vendored_complicated_cargo_library"
 genmode = "Vendored"
 
-[raze.crates.proc-macro2.'0.4.30']
+[package.metadata.raze.crates.proc-macro2.'0.4.30']
 additional_flags = [
     "--cfg=use_proc_macro",
 ]
 
-[raze.crates.regex.'0.2.11']
+[package.metadata.raze.crates.regex.'0.2.11']
 additional_deps = [
   # Add an unused dep
   "//vendored/complicated_cargo_library/cargo:specs"
@@ -34,5 +34,5 @@ additional_flags = [
 # Add an unused environment variable
 additional_env = { NOT_USED_KEY = "not_used_value" }
 
-[raze.crates.conduit-mime-types.'0.7.3']
+[package.metadata.raze.crates.conduit-mime-types.'0.7.3']
 data_attr = "glob([\"data/**\"])"
diff --git a/smoke_test/vendored/hello_cargo_library/Cargo.toml b/smoke_test/vendored/hello_cargo_library/Cargo.toml
index 0e9f8b08e..5632489e0 100644
--- a/smoke_test/vendored/hello_cargo_library/Cargo.toml
+++ b/smoke_test/vendored/hello_cargo_library/Cargo.toml
@@ -11,7 +11,7 @@ fern = "=0.3.5"
 name = "hello_cargo_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/hello_cargo_library/cargo"
 target = "x86_64-unknown-linux-gnu"
 output_buildfile_suffix = "BUILD.bazel"
diff --git a/smoke_test/vendored/non_cratesio_library/Cargo.toml b/smoke_test/vendored/non_cratesio_library/Cargo.toml
index 7523fe628..c553a6409 100644
--- a/smoke_test/vendored/non_cratesio_library/Cargo.toml
+++ b/smoke_test/vendored/non_cratesio_library/Cargo.toml
@@ -16,13 +16,13 @@ log = { git = "https://github.com/rust-lang-nursery/log.git", rev = "bf40d1f563c
 name = "non_cratesio_library"
 path = "src/main.rs"
 
-[raze]
+[package.metadata.raze]
 workspace_path = "//vendored/non_cratesio_library/cargo"
 target = "x86_64-unknown-linux-gnu"
 gen_workspace_prefix = "vendored_non_cratesio_library"
 genmode = "Vendored"
 
-[raze.crates.log.'0.4.11']
+[package.metadata.raze.crates.log.'0.4.11']
 additional_flags = [
     "--cfg=atomic_cas"
 ]