diff --git a/config.example.toml b/config.example.toml
index d0eaa9fd7ffac..6e4654a9a8284 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -429,12 +429,13 @@ changelog-seen = 2
 # Set this to `true` to download unconditionally (useful if e.g. you are only changing doc-comments).
 #download-rustc = false
 
-# Number of codegen units to use for each compiler invocation. A value of 0
-# means "the number of cores on this machine", and 1+ is passed through to the
-# compiler.
+# Number of codegen units to use for each compiler invocation. If specified: a
+# value of 0 means "the number of cores on this machine", and 1+ is passed
+# through to the compiler.
 #
-# Uses the rustc defaults: https://doc.rust-lang.org/rustc/codegen-options/index.html#codegen-units
-#codegen-units = if incremental { 256 } else { 16 }
+# The default value depends on various things, and is also described here:
+# https://doc.rust-lang.org/rustc/codegen-options/index.html#codegen-units
+#codegen-units = if optimize && !debug && !incremental { 1 } else if incremental { 256 } else { 16 }
 
 # Sets the number of codegen units to build the standard library with,
 # regardless of what the codegen-unit setting for the rest of the compiler is.
diff --git a/src/bootstrap/config.rs b/src/bootstrap/config.rs
index 710c8b52194b4..96ef05120fe88 100644
--- a/src/bootstrap/config.rs
+++ b/src/bootstrap/config.rs
@@ -1095,6 +1095,8 @@ impl Config {
         let mut llvm_assertions = None;
         let mut llvm_tests = None;
         let mut llvm_plugins = None;
+        let mut rust_codegen_units = None;
+        let mut rust_codegen_units_std = None;
         let mut debug = None;
         let mut debug_assertions = None;
         let mut debug_assertions_std = None;
@@ -1173,8 +1175,8 @@ impl Config {
                     backends.iter().map(|s| INTERNER.intern_str(s)).collect();
             }
 
-            config.rust_codegen_units = rust.codegen_units.map(threads_from_config);
-            config.rust_codegen_units_std = rust.codegen_units_std.map(threads_from_config);
+            rust_codegen_units = rust.codegen_units.map(threads_from_config);
+            rust_codegen_units_std = rust.codegen_units_std.map(threads_from_config);
             config.rust_profile_use = flags.rust_profile_use.or(rust.profile_use);
             config.rust_profile_generate = flags.rust_profile_generate.or(rust.profile_generate);
             config.download_rustc_commit = config.download_ci_rustc_commit(rust.download_rustc);
@@ -1368,6 +1370,16 @@ impl Config {
         config.llvm_plugins = llvm_plugins.unwrap_or(false);
         config.rust_optimize = optimize.unwrap_or(true);
 
+        let fully_optimized = config.rust_optimize && debug != Some(true) && !config.incremental;
+        if fully_optimized && rust_codegen_units.is_none() {
+            rust_codegen_units = Some(1)
+        }
+        if fully_optimized && rust_codegen_units_std.is_none() {
+            rust_codegen_units_std = Some(1)
+        }
+        config.rust_codegen_units = rust_codegen_units;
+        config.rust_codegen_units_std = rust_codegen_units_std;
+
         let default = debug == Some(true);
         config.rust_debug_assertions = debug_assertions.unwrap_or(default);
         config.rust_debug_assertions_std =
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index 1041d5026690f..33410adcfd8d9 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -31,6 +31,7 @@ Supported values can also be discovered by running `rustc --print code-models`.
 
 ## codegen-units
 
+njn: wrong about 0
 This flag controls how many code generation units the crate is split into. It
 takes an integer greater than 0.
 
@@ -39,6 +40,7 @@ them in parallel. Increasing parallelism may speed up compile times, but may
 also produce slower code. Setting this to 1 may improve the performance of
 generated code, but may be slower to compile.
 
+njn: update
 The default value, if not specified, is 16 for non-incremental builds. For
 incremental builds the default is 256 which allows caching to be more granular.