diff --git a/path/join.ts b/path/join.ts
index 3c09ef727a29..320a1aa7cb2f 100644
--- a/path/join.ts
+++ b/path/join.ts
@@ -20,6 +20,9 @@ import { join as windowsJoin } from "./windows/join.ts";
  * }
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `join` from `@std/path/unstable-join`.
+ *
  * @param paths Paths to be joined and normalized.
  * @returns The joined and normalized path.
  */
diff --git a/path/posix/join.ts b/path/posix/join.ts
index 7bad980ed896..54c6633e8d58 100644
--- a/path/posix/join.ts
+++ b/path/posix/join.ts
@@ -16,6 +16,9 @@ import { normalize } from "./normalize.ts";
  * assertEquals(path, "/foo/bar/baz/asdf");
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `join` from `@std/path/posix/unstable-join`.
+ *
  * @param paths The paths to join.
  * @returns The joined path.
  */
diff --git a/path/windows/join.ts b/path/windows/join.ts
index 58f0e9592149..77fb846e7558 100644
--- a/path/windows/join.ts
+++ b/path/windows/join.ts
@@ -17,6 +17,9 @@ import { normalize } from "./normalize.ts";
  * assertEquals(joined, "C:\\foo\\bar");
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `join` from `@std/path/windows/unstable-join`.
+ *
  * @param paths The paths to join.
  * @returns The joined path.
  */