diff --git a/macro/src/lib.rs b/macro/src/lib.rs
index a8137880ee3..19ce95e0e5a 100644
--- a/macro/src/lib.rs
+++ b/macro/src/lib.rs
@@ -201,6 +201,22 @@ fn validate_type_path(path: &syn::Path, metadata: &Metadata) {
     }
 }
 
+/// Resolves a path, handling the $OUT_DIR placeholder if present.
+/// If $OUT_DIR is present in the path, it's replaced with the actual OUT_DIR environment variable.
+/// Otherwise, the path is resolved relative to CARGO_MANIFEST_DIR.
+fn resolve_path(path_str: &str) -> std::path::PathBuf {
+    if path_str.contains("$OUT_DIR") {
+        let out_dir = std::env::var("OUT_DIR").unwrap_or_else(|_| {
+            abort_call_site!("$OUT_DIR is used in path but OUT_DIR environment variable is not set")
+        });
+        std::path::Path::new(&path_str.replace("$OUT_DIR", &out_dir)).into()
+    } else {
+        let root = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".into());
+        let root_path = std::path::Path::new(&root);
+        root_path.join(path_str)
+    }
+}
+
 /// Fetches metadata in a blocking manner, from a url or file path.
 fn fetch_metadata(args: &RuntimeMetadataArgs) -> Result<subxt_codegen::Metadata, TokenStream> {
     // Do we want to fetch unstable metadata? This only works if fetching from a URL.
@@ -213,9 +229,7 @@ fn fetch_metadata(args: &RuntimeMetadataArgs) -> Result<subxt_codegen::Metadata,
                 "Only one of 'runtime_metadata_path', 'runtime_metadata_insecure_url' or `runtime_path` must be provided"
             );
         };
-        let root = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".into());
-        let root_path = std::path::Path::new(&root);
-        let path = root_path.join(path);
+        let path = resolve_path(path);
 
         let metadata = wasm_loader::from_wasm_file(&path).map_err(|e| e.into_compile_error())?;
         return Ok(metadata);
@@ -232,9 +246,8 @@ fn fetch_metadata(args: &RuntimeMetadataArgs) -> Result<subxt_codegen::Metadata,
                 )
             }
 
-            let root = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".into());
-            let root_path = std::path::Path::new(&root);
-            let path = root_path.join(rest_of_path);
+            let path = resolve_path(rest_of_path);
+
             subxt_utils_fetchmetadata::from_file_blocking(&path)
                 .and_then(|b| subxt_codegen::Metadata::decode(&mut &*b).map_err(Into::into))
                 .map_err(|e| CodegenError::Other(e.to_string()).into_compile_error())?
diff --git a/subxt/src/lib.rs b/subxt/src/lib.rs
index 57b8e02e340..b4eb86f68d3 100644
--- a/subxt/src/lib.rs
+++ b/subxt/src/lib.rs
@@ -151,6 +151,15 @@ pub mod ext {
 /// mod polkadot {}
 /// ```
 ///
+/// You can use the `$OUT_DIR` placeholder in the path to reference metadata generated at build time:
+///
+/// ```rust,ignore
+/// #[subxt::subxt(
+///     runtime_metadata_path = "$OUT_DIR/metadata.scale",
+/// )]
+/// mod polkadot {}
+/// ```
+///
 /// ## Using a WASM runtime via `runtime_path = "..."`
 ///
 /// This requires the `runtime-wasm-path` feature flag.
@@ -164,6 +173,15 @@ pub mod ext {
 /// mod polkadot {}
 /// ```
 ///
+/// You can also use the `$OUT_DIR` placeholder in the path to reference WASM files generated at build time:
+///
+/// ```rust,ignore
+/// #[subxt::subxt(
+///     runtime_path = "$OUT_DIR/runtime.wasm",
+/// )]
+/// mod polkadot {}
+/// ```
+///
 /// ## Connecting to a node to download metadata via `runtime_metadata_insecure_url = "..."`
 ///
 /// This will, at compile time, connect to the JSON-RPC interface for some node at the URL given,