diff --git a/docs/user/Embedding-Build-Tools.md b/docs/user/Embedding-Build-Tools.md
index e7d1acf12b..47813460bf 100644
--- a/docs/user/Embedding-Build-Tools.md
+++ b/docs/user/Embedding-Build-Tools.md
@@ -148,6 +148,23 @@ The Python packages and their versions are specified as if used with `pip`:
       ...
   </configuration>
   ```
+- The **requirementsFile** element declares a path to a pip-compatible `requirements.txt` file.
+  The plugin forwards this file directly to pip (`pip install -r`), allowing full use of pip’s native dependency format.
+
+  ```xml
+  <configuration>
+      <requirementsFile>requirements.txt</requirementsFile>
+      ...
+  </configuration>
+  ```
+
+  > **_NOTE:_**
+  > Exactly one of `packages` or `requirementsFile` must be configured.
+  > When `requirementsFile` is used:
+  > - the GraalPy lock file is not created or used
+  > - the `lock-packages` goal is disabled
+  > - dependency locking must be handled by pip (e.g., `pip freeze`)
+
 
 - The **resourceDirectory** element can specify the relative [Java resource path](#java-resource-path).
   Remember to use `VirtualFileSystem$Builder#resourceDirectory` when configuring the `VirtualFileSystem` in Java.