From eef29546d776ce0d413cfdc6ec9ba251cd5914e8 Mon Sep 17 00:00:00 2001
From: meelahme <jameelahmercer@gmail.com>
Date: Thu, 16 Oct 2025 12:02:37 -0700
Subject: [PATCH] fix(influxdb3): add python directory requirement note to
 plugins setup

---
 .../influxdb3-get-started/processing-engine.md     |  3 +++
 content/shared/influxdb3-plugins/_index.md         | 14 ++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/content/shared/influxdb3-get-started/processing-engine.md b/content/shared/influxdb3-get-started/processing-engine.md
index 009b3d4ee..cf54ca3e8 100644
--- a/content/shared/influxdb3-get-started/processing-engine.md
+++ b/content/shared/influxdb3-get-started/processing-engine.md
@@ -48,6 +48,9 @@ when starting the {{% product-name %}} server.
 `PLUGIN_DIR` is your file system location for storing [plugin](#plugin) files for
 the processing engine to run.
 
+> [!Note]
+> If you manually installed from tar.gz, ensure the `influxdb3` binary and `python/` directory remain in the same parent location. The install script handles this automatically.
+
 {{% code-placeholders "PLUGIN_DIR" %}}
 <!-- pytest.mark.skip -->
 ```bash
diff --git a/content/shared/influxdb3-plugins/_index.md b/content/shared/influxdb3-plugins/_index.md
index 14dace282..d127cbc73 100644
--- a/content/shared/influxdb3-plugins/_index.md
+++ b/content/shared/influxdb3-plugins/_index.md
@@ -34,6 +34,20 @@ Once you have all the prerequisites in place, follow these steps to implement th
 
 To activate the Processing Engine, start your {{% product-name %}} server with the `--plugin-dir` flag. This flag tells InfluxDB where to load your plugin files.
 
+> [!Important]
+> #### Keep influxdb3 and python/ together
+>
+> The influxdb3 binary requires the adjacent `python/` directory to function. 
+> If you manually extract from tar.gz, keep them in the same parent directory:
+>
+> {{< filesystem-diagram >}}
+>   - your-install-location/
+>   - influxdb3
+>   - python/
+> {{< /filesystem-diagram >}}
+>
+> Add the directory (not just the binary) to your PATH. Moving only the binary will cause Python runtime errors.
+
 {{% code-placeholders "NODE_ID|OBJECT_STORE_TYPE|PLUGIN_DIR" %}}
 
 ```bash