[ty] Support finding dependencies in system Pythons that ty is installed into

Fixes an issue where ty couldn't resolve imports from packages installed
in a system Python environment when ty itself was installed directly in
that system Python (rather than in a virtual environment).

Previously, `SysPrefixPathOrigin::SelfEnvironment` was treated as requiring
a virtual environment (with `pyvenv.cfg`), which caused discovery to fail
for system Python installations. This change allows ty to fall back to
treating its own environment as a `SystemEnvironment` when no `pyvenv.cfg`
is found.

Additionally, this change implements correct priority ordering:
- When ty is installed in a virtual environment (e.g., `uvx --with ...`),
  ty's venv takes priority over other discovered environments
- When ty is installed in a system Python, discovered environments (like
  `.venv`) take priority over the system Python's site-packages

Fixes astral-sh/ty#2068

https://claude.ai/code/session_01885t5j7zeT78vRZCtu8X9C

Author: claude

crates/ty/tests/cli/python_environment.rs

@@ -2181,7 +2181,7 @@ fn ty_environment_and_active_environment() -> anyhow::Result<()> {
 }
 
 /// When ty is installed in a system environment rather than a virtual environment, it should
-/// not include the environment's site-packages in its search path.
+/// include the environment's site-packages in its search path.
 #[test]
 fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     let ty_system_site_packages = if cfg!(windows) {
@@ -2199,7 +2199,7 @@ fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     let ty_package_path = format!("{ty_system_site_packages}/system_package/__init__.py");
 
     let case = CliTest::with_files([
-        // Package in system Python installation (should NOT be discovered)
+        // Package in system Python installation (should be discovered)
         (ty_package_path.as_str(), "class SystemClass: ..."),
         // Note: NO pyvenv.cfg - this is a system installation, not a venv
         (
@@ -2211,20 +2211,92 @@ fn ty_environment_is_system_not_virtual() -> anyhow::Result<()> {
     ])?
     .with_ty_at(ty_executable_path)?;
 
+    assert_cmd_snapshot!(case.command(), @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
+/// When ty is installed in a system environment and there's also a local `.venv`,
+/// the `.venv` should take priority over the system environment's site-packages.
+/// This is the opposite of when ty is installed in a virtual environment (like `uvx --with ...`),
+/// where ty's venv takes priority.
+#[test]
+fn ty_system_environment_and_local_venv() -> anyhow::Result<()> {
+    let ty_system_site_packages = if cfg!(windows) {
+        "system-python/Lib/site-packages"
+    } else {
+        "system-python/lib/python3.13/site-packages"
+    };
+
+    let ty_executable_path = if cfg!(windows) {
+        "system-python/Scripts/ty.exe"
+    } else {
+        "system-python/bin/ty"
+    };
+
+    let local_venv_site_packages = if cfg!(windows) {
+        ".venv/Lib/site-packages"
+    } else {
+        ".venv/lib/python3.13/site-packages"
+    };
+
+    let ty_unique_package = format!("{ty_system_site_packages}/system_package/__init__.py");
+    let local_unique_package = format!("{local_venv_site_packages}/local_package/__init__.py");
+    let ty_conflicting_package = format!("{ty_system_site_packages}/shared_package/__init__.py");
+    let local_conflicting_package =
+        format!("{local_venv_site_packages}/shared_package/__init__.py");
+
+    let case = CliTest::with_files([
+        (ty_unique_package.as_str(), "class SystemEnvClass: ..."),
+        (local_unique_package.as_str(), "class LocalClass: ..."),
+        (ty_conflicting_package.as_str(), "class FromSystemEnv: ..."),
+        (
+            local_conflicting_package.as_str(),
+            "class FromLocalVenv: ...",
+        ),
+        // Note: NO pyvenv.cfg for system-python - this is a system installation, not a venv
+        (
+            ".venv/pyvenv.cfg",
+            r"
+            home = ./
+            version = 3.13
+            ",
+        ),
+        (
+            "test.py",
+            r"
+            # Should resolve from ty's system environment
+            from system_package import SystemEnvClass
+            # Should resolve from local .venv
+            from local_package import LocalClass
+            # Should resolve from .venv (takes precedence over system Python)
+            from shared_package import FromLocalVenv
+            # Should NOT resolve (shadowed by .venv version)
+            from shared_package import FromSystemEnv
+            ",
+        ),
+    ])?
+    .with_ty_at(ty_executable_path)?;
+
     assert_cmd_snapshot!(case.command(), @"
     success: false
     exit_code: 1
     ----- stdout -----
-    error[unresolved-import]: Cannot resolve imported module `system_package`
-     --> test.py:2:6
+    error[unresolved-import]: Module `shared_package` has no member `FromSystemEnv`
+     --> test.py:9:28
       |
-    2 | from system_package import SystemClass
-      |      ^^^^^^^^^^^^^^
+    7 | from shared_package import FromLocalVenv
+    8 | # Should NOT resolve (shadowed by .venv version)
+    9 | from shared_package import FromSystemEnv
+      |                            ^^^^^^^^^^^^^
       |
-    info: Searched in the following paths during module resolution:
-    info:   1. <temp_dir>/ (first-party code)
-    info:   2. vendored://stdlib (stdlib typeshed stubs vendored by ty)
-    info: make sure your Python environment is properly configured: https://docs.astral.sh/ty/modules/#python-environment
     info: rule `unresolved-import` is enabled by default
 
     Found 1 diagnostic

crates/ty_project/src/metadata/options.rs

@@ -183,14 +183,13 @@ impl Options {
             }
         };
 
-        let self_site_packages = self_environment_search_paths(
+        let self_environment = self_environment_search_paths(
             python_environment
                 .as_ref()
                 .map(ty_python_semantic::PythonEnvironment::origin)
                 .cloned(),
             system,
-        )
-        .unwrap_or_default();
+        );
 
         let site_packages_paths = if let Some(python_environment) = python_environment.as_ref() {
             let site_packages_paths = python_environment
@@ -209,10 +208,22 @@ impl Options {
                     }
                 }
             };
-            self_site_packages.concatenate(site_packages_paths)
+            match self_environment {
+                // When ty is installed in a virtual environment (e.g., `uvx --with ...`),
+                // the self-environment takes priority over the discovered environment.
+                Some((self_site_packages, true)) => {
+                    self_site_packages.concatenate(site_packages_paths)
+                }
+                // When ty is installed in a system Python, the discovered environment
+                // (e.g., `.venv`) takes priority over the self-environment.
+                Some((self_site_packages, false)) => {
+                    site_packages_paths.concatenate(self_site_packages)
+                }
+                None => site_packages_paths,
+            }
         } else {
             tracing::debug!("No virtual environment found");
-            self_site_packages
+            self_environment.map(|(paths, _)| paths).unwrap_or_default()
         };
 
         let real_stdlib_path = python_environment.as_ref().and_then(|python_environment| {
@@ -521,10 +532,14 @@ impl Options {
 ///
 /// Since ty may be executed from an arbitrary non-Python location, errors during discovery of ty's
 /// environment are not raised, instead [`None`] is returned.
+///
+/// Returns a tuple of (`site_packages`, `is_virtual_env`). When the self-environment is a virtual
+/// environment (e.g., `uvx --with ...`), it should take priority over other environments.
+/// When it's a system Python, other environments (like `.venv`) should take priority.
 fn self_environment_search_paths(
     existing_origin: Option<SysPrefixPathOrigin>,
     system: &dyn System,
-) -> Option<SitePackagesPaths> {
+) -> Option<(SitePackagesPaths, bool)> {
     if existing_origin.is_some_and(|origin| !origin.allows_concatenation_with_self_environment()) {
         return None;
     }
@@ -538,15 +553,17 @@ fn self_environment_search_paths(
         .inspect_err(|err| tracing::debug!("Failed to discover ty's environment: {err}"))
         .ok()?;
 
+    let is_virtual_env = environment.is_virtual();
+
     let search_paths = environment
         .site_packages_paths(system)
         .inspect_err(|err| {
             tracing::debug!("Failed to discover site-packages in ty's environment: {err}");
         })
-        .ok();
+        .ok()?;
 
     tracing::debug!("Using site-packages from ty's environment");
-    search_paths
+    Some((search_paths, is_virtual_env))
 }
 
 #[derive(

crates/ty_site_packages/src/lib.rs

@@ -270,6 +270,11 @@ impl PythonEnvironment {
             Self::System(env) => &env.root_path.origin,
         }
     }
+
+    /// Returns `true` if this is a virtual environment (has a `pyvenv.cfg` file).
+    pub fn is_virtual(&self) -> bool {
+        matches!(self, Self::Virtual(_))
+    }
 }
 
 /// Enumeration of the subdirectories of `sys.prefix` that could contain a
@@ -1618,14 +1623,8 @@ impl SysPrefixPathOrigin {
             | Self::PythonCliFlag
             | Self::Editor
             | Self::DerivedFromPyvenvCfg
-            | Self::CondaPrefixVar => false,
-            // It's not strictly true that the self environment must be virtual, e.g., ty could be
-            // installed in a system Python environment and users may expect us to respect
-            // dependencies installed alongside it. However, we're intentionally excluding support
-            // for this to start. Note a change here has downstream implications, i.e., we probably
-            // don't want the packages in a system environment to take precedence over those in a
-            // virtual environment and would need to reverse the ordering in that case.
-            Self::SelfEnvironment => true,
+            | Self::CondaPrefixVar
+            | Self::SelfEnvironment => false,
         }
     }
 
@@ -2095,6 +2094,20 @@ mod tests {
         );
     }
 
+    #[test]
+    fn can_find_site_packages_directory_no_virtual_env_at_origin_self_environment() {
+        // Test that ty can discover dependencies in a system Python environment
+        // that it's installed into (issue #2068).
+        let test = PythonEnvironmentTestCase {
+            system: TestSystem::default(),
+            minor_version: 13,
+            free_threaded: false,
+            origin: SysPrefixPathOrigin::SelfEnvironment,
+            virtual_env: None,
+        };
+        test.run();
+    }
+
     #[test]
     fn can_find_site_packages_directory_venv_style_version_field_in_pyvenv_cfg() {
         // Shouldn't be converted to an mdtest because we want to assert