diff --git a/components/esp32/include/esp_attr.h b/components/esp32/include/esp_attr.h
index c9e3879ee..7a3ec771d 100644
--- a/components/esp32/include/esp_attr.h
+++ b/components/esp32/include/esp_attr.h
@@ -84,4 +84,13 @@
 
 #define _COUNTER_STRINGIFY(COUNTER) #COUNTER
 
+/* Use IDF_DEPRECATED attribute to mark anything deprecated from use in
+   ESP-IDF's own source code, but not deprecated for external users.
+*/
+#ifdef IDF_CI_BUILD
+#define IDF_DEPRECATED(REASON) __attribute__((deprecated(REASON)))
+#else
+#define IDF_DEPRECATED(REASON)
+#endif
+
 #endif /* __ESP_ATTR_H__ */
diff --git a/components/nvs_flash/include/nvs.h b/components/nvs_flash/include/nvs.h
index 13f5b9552..f30ffd03a 100644
--- a/components/nvs_flash/include/nvs.h
+++ b/components/nvs_flash/include/nvs.h
@@ -17,6 +17,7 @@
 #include <stdint.h>
 #include <stddef.h>
 #include <stdbool.h>
+#include "esp_attr.h"
 #include "esp_err.h"
 
 #ifdef __cplusplus
@@ -31,7 +32,7 @@ typedef uint32_t nvs_handle_t;
 /*
  * Pre-IDF V4.0 uses nvs_handle, so leaving the original typedef here for compatibility.
  */
-typedef nvs_handle_t nvs_handle;
+typedef nvs_handle_t nvs_handle IDF_DEPRECATED("Replace with nvs_handle_t");
 
 #define ESP_ERR_NVS_BASE                    0x1100                     /*!< Starting number of error codes */
 #define ESP_ERR_NVS_NOT_INITIALIZED         (ESP_ERR_NVS_BASE + 0x01)  /*!< The storage driver is not initialized */
@@ -74,7 +75,7 @@ typedef enum {
 /*
  * Pre-IDF V4.0 uses nvs_open_mode, so leaving the original typedef here for compatibility.
  */
-typedef nvs_open_mode_t nvs_open_mode
+typedef nvs_open_mode_t nvs_open_mode IDF_DEPRECATED("Replace with nvs_open_mode_t");
 
 typedef enum {
     NVS_TYPE_U8    = 0x01,
diff --git a/docs/Doxyfile b/docs/Doxyfile
index cd92c6909..c48ca6211 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -232,6 +232,7 @@ MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 PREDEFINED             = \
     __attribute__(x)= \
+    IDF_DEPRECATED(X)= \
     IRAM_ATTR= \
     configSUPPORT_DYNAMIC_ALLOCATION=1 \
     configSUPPORT_STATIC_ALLOCATION=1 \
diff --git a/tools/ci/configure_ci_environment.sh b/tools/ci/configure_ci_environment.sh
index 1d4380ad5..73721746e 100644
--- a/tools/ci/configure_ci_environment.sh
+++ b/tools/ci/configure_ci_environment.sh
@@ -33,4 +33,4 @@ unset REF
 
 # Compiler flags to thoroughly check the IDF code in some CI jobs
 # (Depends on default options '-Wno-error=XXX' used in the IDF build system)
-export PEDANTIC_CFLAGS="-Werror -Werror=deprecated-declarations -Werror=unused-variable -Werror=unused-but-set-variable -Werror=unused-function"
+export PEDANTIC_CFLAGS="-DIDF_CI_BUILD -Werror -Werror=deprecated-declarations -Werror=unused-variable -Werror=unused-but-set-variable -Werror=unused-function"