From c36e72876f026819e3b815cae0d4a24709234fe6 Mon Sep 17 00:00:00 2001
From: Jason Satein <8883967+clovehitch@users.noreply.github.com>
Date: Tue, 4 Aug 2026 08:36:11 -0700
Subject: [PATCH] Closes #22567: Warn that a custom script file name must not
 shadow an installed Python module (#22804)

---
 docs/customization/custom-scripts.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/customization/custom-scripts.md b/docs/customization/custom-scripts.md
index f7aacb238..e18d7f700 100644
--- a/docs/customization/custom-scripts.md
+++ b/docs/customization/custom-scripts.md
@@ -23,6 +23,9 @@ Custom scripts are Python code which exists outside the NetBox code base, so the
 
 ## Writing Custom Scripts
 
+!!! warning "Choose a unique file name"
+    A script file's name (without the `.py` extension) becomes its Python module name when the script is loaded. A script file must not share its name with a NetBox application (e.g. `circuits.py` or `dcim.py`) or any other installed Python module: the script will shadow that module in Python's import system and can break unrelated functionality. Choose a unique, descriptive file name, such as `circuit_maintenance.py`.
+
 All custom scripts must inherit from the `extras.scripts.Script` base class. This class provides the functionality necessary to generate forms and log activity.
 
 ```python