add support for configuring PYTHONPATH

Author: joshuadavidthomas

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ### Added
 
+- Added `pythonpath` configuration option for specifying additional Python import paths
 - Added documentation for Zed extension
 - Added documentation for setting up Sublime Text
 

crates/djls-conf/src/lib.rs

@@ -38,6 +38,8 @@ pub struct Settings {
     venv_path: Option<String>,
     django_settings_module: Option<String>,
     #[serde(default)]
+    pythonpath: Vec<String>,
+    #[serde(default)]
     tagspecs: Vec<TagSpecDef>,
 }
 
@@ -54,6 +56,9 @@ impl Settings {
             settings.django_settings_module = overrides
                 .django_settings_module
                 .or(settings.django_settings_module);
+            if !overrides.pythonpath.is_empty() {
+                settings.pythonpath = overrides.pythonpath;
+            }
             if !overrides.tagspecs.is_empty() {
                 settings.tagspecs = overrides.tagspecs;
             }
@@ -120,6 +125,11 @@ impl Settings {
         self.django_settings_module.as_deref()
     }
 
+    #[must_use]
+    pub fn pythonpath(&self) -> &[String] {
+        &self.pythonpath
+    }
+
     #[must_use]
     pub fn tagspecs(&self) -> &[TagSpecDef] {
         &self.tagspecs
@@ -148,6 +158,7 @@ mod tests {
                     debug: false,
                     venv_path: None,
                     django_settings_module: None,
+                    pythonpath: vec![],
                     tagspecs: vec![],
                 }
             );
@@ -185,6 +196,24 @@ mod tests {
             );
         }
 
+        #[test]
+        fn test_load_pythonpath_config() {
+            let dir = tempdir().unwrap();
+            fs::write(
+                dir.path().join("djls.toml"),
+                r#"pythonpath = ["/path/to/lib", "/another/path"]"#,
+            )
+            .unwrap();
+            let settings = Settings::new(Utf8Path::from_path(dir.path()).unwrap(), None).unwrap();
+            assert_eq!(
+                settings,
+                Settings {
+                    pythonpath: vec!["/path/to/lib".to_string(), "/another/path".to_string()],
+                    ..Default::default()
+                }
+            );
+        }
+
         #[test]
         fn test_load_dot_djls_toml_only() {
             let dir = tempdir().unwrap();

crates/djls-project/src/inspector.rs

@@ -40,20 +40,23 @@ pub fn query<Q: InspectorRequest>(db: &dyn ProjectDb, request: &Q) -> Option<Q::
     let interpreter = project.interpreter(db);
     let project_path = project.root(db);
     let django_settings_module = project.django_settings_module(db);
+    let pythonpath = project.pythonpath(db);
 
     tracing::debug!(
-        "Inspector query '{}': interpreter={:?}, project_path={}, django_settings_module={:?}",
+        "Inspector query '{}': interpreter={:?}, project_path={}, django_settings_module={:?}, pythonpath={:?}",
         Q::NAME,
         interpreter,
         project_path,
-        django_settings_module
+        django_settings_module,
+        pythonpath
     );
 
     let inspector = db.inspector();
     match inspector.query::<Q, Q::Response>(
         interpreter,
         project_path,
         django_settings_module.as_deref(),
+        pythonpath,
         request,
     ) {
         Ok(response) if response.ok => {
@@ -128,10 +131,16 @@ impl Inspector {
         interpreter: &Interpreter,
         project_path: &Utf8Path,
         django_settings_module: Option<&str>,
+        pythonpath: &[String],
         request: &Q,
     ) -> Result<InspectorResponse<R>> {
-        self.inner()
-            .query::<Q, R>(interpreter, project_path, django_settings_module, request)
+        self.inner().query::<Q, R>(
+            interpreter,
+            project_path,
+            django_settings_module,
+            pythonpath,
+            request,
+        )
     }
 
     /// Manually close the inspector process
@@ -172,9 +181,15 @@ impl InspectorInner {
         interpreter: &Interpreter,
         project_path: &Utf8Path,
         django_settings_module: Option<&str>,
+        pythonpath: &[String],
         request: &Q,
     ) -> Result<InspectorResponse<R>> {
-        self.ensure_process(interpreter, project_path, django_settings_module)?;
+        self.ensure_process(
+            interpreter,
+            project_path,
+            django_settings_module,
+            pythonpath,
+        )?;
 
         let process = self.process_mut();
         let response = process.query::<Q, R>(request)?;
@@ -196,6 +211,7 @@ impl InspectorInner {
         interpreter: &Interpreter,
         project_path: &Utf8Path,
         django_settings_module: Option<&str>,
+        pythonpath: &[String],
     ) -> Result<()> {
         let needs_new_process = match &mut self.process {
             None => {
@@ -208,11 +224,17 @@ impl InspectorInner {
                 let path_changed = state.project_path != project_path;
                 let settings_changed =
                     state.django_settings_module.as_deref() != django_settings_module;
-
-                if not_running || interpreter_changed || path_changed || settings_changed {
+                let pythonpath_changed = state.pythonpath != pythonpath;
+
+                if not_running
+                    || interpreter_changed
+                    || path_changed
+                    || settings_changed
+                    || pythonpath_changed
+                {
                     tracing::debug!(
-                        "Inspector process needs restart: not_running={}, interpreter_changed={}, path_changed={}, settings_changed={}",
-                        not_running, interpreter_changed, path_changed, settings_changed
+                        "Inspector process needs restart: not_running={}, interpreter_changed={}, path_changed={}, settings_changed={}, pythonpath_changed={}",
+                        not_running, interpreter_changed, path_changed, settings_changed, pythonpath_changed
                     );
                     true
                 } else {
@@ -224,13 +246,15 @@ impl InspectorInner {
         if needs_new_process {
             self.shutdown_process();
             tracing::info!(
-                "Spawning new inspector process with django_settings_module={:?}",
-                django_settings_module
+                "Spawning new inspector process with django_settings_module={:?}, pythonpath={:?}",
+                django_settings_module,
+                pythonpath
             );
             self.process = Some(InspectorProcess::spawn(
                 interpreter.to_owned(),
-                project_path.to_path_buf(),
+                &project_path.to_path_buf(),
                 django_settings_module.map(String::from),
+                pythonpath.to_vec(),
             )?);
         }
         Ok(())
@@ -288,6 +312,7 @@ struct InspectorProcess {
     interpreter: Interpreter,
     project_path: Utf8PathBuf,
     django_settings_module: Option<String>,
+    pythonpath: Vec<String>,
     // keep a handle on the tempfile so it doesn't get cleaned up
     _zipapp_file_handle: InspectorFile,
 }
@@ -296,30 +321,36 @@ impl InspectorProcess {
     /// Spawn a new inspector process
     pub fn spawn(
         interpreter: Interpreter,
-        project_path: Utf8PathBuf,
+        project_path: &Utf8PathBuf,
         django_settings_module: Option<String>,
+        pythonpath: Vec<String>,
     ) -> Result<Self> {
         let zipapp_file = InspectorFile::create()?;
 
         let python_path = interpreter
-            .python_path(&project_path)
+            .python_path(project_path)
             .context("Failed to resolve Python interpreter")?;
 
         let mut cmd = Command::new(&python_path);
         cmd.arg(zipapp_file.path())
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
             .stderr(Stdio::piped()) // Capture stderr instead of inheriting
-            .current_dir(&project_path);
+            .current_dir(project_path);
 
-        if let Ok(pythonpath) = std::env::var("PYTHONPATH") {
-            let mut paths = vec![project_path.to_string()];
-            paths.push(pythonpath);
-            cmd.env("PYTHONPATH", paths.join(":"));
-        } else {
-            cmd.env("PYTHONPATH", project_path.clone());
+        let mut paths = vec![project_path.to_string()];
+        paths.extend(pythonpath.iter().cloned());
+        if let Ok(env_pythonpath) = std::env::var("PYTHONPATH") {
+            paths.push(env_pythonpath);
         }
 
+        #[cfg(unix)]
+        let path_separator = ":";
+        #[cfg(windows)]
+        let path_separator = ";";
+
+        cmd.env("PYTHONPATH", paths.join(path_separator));
+
         // Set Django settings module if we have one
         if let Some(ref module) = django_settings_module {
             tracing::debug!("Setting DJANGO_SETTINGS_MODULE={}", module);
@@ -355,8 +386,9 @@ impl InspectorProcess {
             stdout,
             last_used: Instant::now(),
             interpreter,
-            project_path,
+            project_path: project_path.to_owned(),
             django_settings_module,
+            pythonpath,
             _zipapp_file_handle: zipapp_file,
         })
     }

crates/djls-project/src/project.rs

@@ -23,6 +23,9 @@ pub struct Project {
     /// Django settings module (e.g., "myproject.settings")
     #[returns(ref)]
     pub django_settings_module: Option<String>,
+    /// Additional Python import paths (PYTHONPATH entries)
+    #[returns(ref)]
+    pub pythonpath: Vec<String>,
 }
 
 impl Project {
@@ -31,6 +34,7 @@ impl Project {
         root: &Utf8Path,
         venv_path: Option<&str>,
         django_settings_module: Option<&str>,
+        pythonpath: &[String],
     ) -> Project {
         let interpreter = Interpreter::discover(venv_path);
 
@@ -75,6 +79,7 @@ impl Project {
             root.to_path_buf(),
             interpreter,
             resolved_django_settings_module,
+            pythonpath.to_vec(),
         )
     }
 

crates/djls-server/src/db.rs

@@ -116,7 +116,7 @@ impl DjangoDatabase {
         self.settings.lock().unwrap().clone()
     }
 
-    /// Update the settings, potentially updating the project if `venv_path` or `django_settings_module` changed
+    /// Update the settings, potentially updating the project if `venv_path`, `django_settings_module`, or `pythonpath` changed
     ///
     /// # Panics
     ///
@@ -126,6 +126,7 @@ impl DjangoDatabase {
             let old = self.settings();
             old.venv_path() != settings.venv_path()
                 || old.django_settings_module() != settings.django_settings_module()
+                || old.pythonpath() != settings.pythonpath()
         };
 
         *self.settings.lock().unwrap() = settings;
@@ -145,6 +146,7 @@ impl DjangoDatabase {
             root,
             settings.venv_path(),
             settings.django_settings_module(),
+            settings.pythonpath(),
         );
         *self.project.lock().unwrap() = Some(project);
     }

docs/configuration.md

@@ -36,6 +36,19 @@ The server needs access to your virtual environment to discover installed Django
 - Your virtual environment is in a non-standard location
 - Auto-detection fails for your setup
 
+### `pythonpath`
+
+**Default:** `[]` (empty list)
+
+Additional directories to add to Python's import search path when the inspector process runs. These paths are added to `PYTHONPATH` alongside the project root and any existing `PYTHONPATH` environment variable.
+
+**When to configure:**
+
+- Your project has a non-standard structure where Django code imports from directories outside the project root
+- You're working in a monorepo where Django imports shared packages from other directories
+- Your project depends on internal libraries in non-standard locations
+- You need to make additional packages importable for Django introspection
+
 ### `debug`
 
 **Default:** `false`
@@ -66,7 +79,8 @@ Pass configuration through your editor's LSP client using `initializationOptions
 ```json
 {
   "django_settings_module": "myproject.settings",
-  "venv_path": "/path/to/venv"
+  "venv_path": "/path/to/venv",
+  "pythonpath": ["/path/to/shared/libs"]
 }
 ```
 
@@ -82,6 +96,7 @@ If you use `pyproject.toml`, add a `[tool.djls]` section:
 [tool.djls]
 django_settings_module = "myproject.settings"
 venv_path = "/path/to/venv"  # Optional: only if auto-detection fails
+pythonpath = ["/path/to/shared/libs"]  # Optional: additional import paths
 ```
 
 If you prefer a dedicated config file or don't use `pyproject.toml`, you can use `djls.toml` (same settings, no `[tool.djls]` table).