From 0cecc22d8b18a6a235107d16f2851763f70666b0 Mon Sep 17 00:00:00 2001
From: Alex Waygood <alex.waygood@gmail.com>
Date: Mon, 6 Oct 2025 15:00:07 +0100
Subject: [PATCH] [ty] Rename `extra-paths` to `non-environment-paths`, and
 `--extra-search-path` to `--non-environment-search-path`

---
 crates/ty/docs/cli.md                         |  4 +-
 crates/ty/docs/configuration.md               |  4 +-
 crates/ty/src/args.rs                         | 16 ++++----
 crates/ty/tests/cli/main.rs                   |  6 +--
 crates/ty/tests/file_watching.rs              | 12 +++---
 crates/ty_combine/src/lib.rs                  | 12 +++---
 crates/ty_project/src/metadata/options.rs     | 23 ++++++------
 crates/ty_project/src/metadata/value.rs       |  2 +-
 .../resources/mdtest/import/case_sensitive.md |  2 +-
 .../mdtest/import/partial_stub_packages.md    | 14 +++----
 .../resources/mdtest/import/stub_packages.md  | 16 ++++----
 .../src/module_resolver/path.rs               | 37 ++++++++++---------
 .../src/module_resolver/resolver.rs           |  8 ++--
 crates/ty_python_semantic/src/program.rs      | 12 +++---
 crates/ty_test/src/config.rs                  |  6 +--
 crates/ty_test/src/lib.rs                     |  5 ++-
 ty.schema.json                                |  2 +-
 17 files changed, 95 insertions(+), 86 deletions(-)

diff --git a/crates/ty/docs/cli.md b/crates/ty/docs/cli.md
index 83de0b3d6d..b770f75079 100644
--- a/crates/ty/docs/cli.md
+++ b/crates/ty/docs/cli.md
@@ -54,10 +54,10 @@ over all configuration files.</p>
 </dd><dt id="ty-check--exclude"><a href="#ty-check--exclude"><code>--exclude</code></a> <i>exclude</i></dt><dd><p>Glob patterns for files to exclude from type checking.</p>
 <p>Uses gitignore-style syntax to exclude files and directories from type checking. Supports patterns like <code>tests/</code>, <code>*.tmp</code>, <code>**/__pycache__/**</code>.</p>
 </dd><dt id="ty-check--exit-zero"><a href="#ty-check--exit-zero"><code>--exit-zero</code></a></dt><dd><p>Always use exit code 0, even when there are error-level diagnostics</p>
-</dd><dt id="ty-check--extra-search-path"><a href="#ty-check--extra-search-path"><code>--extra-search-path</code></a> <i>path</i></dt><dd><p>Additional path to use as a module-resolution source (can be passed multiple times).</p>
-<p>This is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use <code>--python</code> to point ty to your Python environment if it is in an unusual location.</p>
 </dd><dt id="ty-check--help"><a href="#ty-check--help"><code>--help</code></a>, <code>-h</code></dt><dd><p>Print help (see a summary with '-h')</p>
 </dd><dt id="ty-check--ignore"><a href="#ty-check--ignore"><code>--ignore</code></a> <i>rule</i></dt><dd><p>Disables the rule. Can be specified multiple times.</p>
+</dd><dt id="ty-check--non-environment-search-path"><a href="#ty-check--non-environment-search-path"><code>--non-environment-search-path</code></a> <i>path</i></dt><dd><p>Additional path to use as a module-resolution source (can be passed multiple times).</p>
+<p>This is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use <code>--python</code> to point ty to your Python environment if it is in an unusual location.</p>
 </dd><dt id="ty-check--output-format"><a href="#ty-check--output-format"><code>--output-format</code></a> <i>output-format</i></dt><dd><p>The format to use for printing diagnostic messages</p>
 <p>Possible values:</p>
 <ul>
diff --git a/crates/ty/docs/configuration.md b/crates/ty/docs/configuration.md
index 248e0f547c..00289986d1 100644
--- a/crates/ty/docs/configuration.md
+++ b/crates/ty/docs/configuration.md
@@ -30,7 +30,7 @@ division-by-zero = "ignore"
 
 ## `environment`
 
-### `extra-paths`
+### `non-environment-paths`
 
 User-provided paths that should take first priority in module resolution.
 
@@ -49,7 +49,7 @@ configuration setting.
 
 ```toml
 [tool.ty.environment]
-extra-paths = ["./shared/my-search-path"]
+non-environment-paths = ["./shared/my-search-path"]
 ```
 
 ---
diff --git a/crates/ty/src/args.rs b/crates/ty/src/args.rs
index 8ec32c8c63..18e5f19063 100644
--- a/crates/ty/src/args.rs
+++ b/crates/ty/src/args.rs
@@ -72,7 +72,7 @@ pub(crate) struct CheckCommand {
     /// modules that are not installed into your Python environment in a conventional way.
     /// Use `--python` to point ty to your Python environment if it is in an unusual location.
     #[arg(long, value_name = "PATH")]
-    pub(crate) extra_search_path: Option<Vec<SystemPathBuf>>,
+    pub(crate) non_environment_search_path: Option<Vec<SystemPathBuf>>,
 
     /// Python version to assume when resolving types.
     ///
@@ -184,12 +184,14 @@ impl CheckCommand {
                     .map(|platform| RangedValue::cli(platform.into())),
                 python: self.python.map(RelativePathBuf::cli),
                 typeshed: self.typeshed.map(RelativePathBuf::cli),
-                extra_paths: self.extra_search_path.map(|extra_search_paths| {
-                    extra_search_paths
-                        .into_iter()
-                        .map(RelativePathBuf::cli)
-                        .collect()
-                }),
+                non_environment_paths: self.non_environment_search_path.map(
+                    |non_environment_paths| {
+                        non_environment_paths
+                            .into_iter()
+                            .map(RelativePathBuf::cli)
+                            .collect()
+                    },
+                ),
                 ..EnvironmentOptions::default()
             }),
             terminal: Some(TerminalOptions {
diff --git a/crates/ty/tests/cli/main.rs b/crates/ty/tests/cli/main.rs
index 335f288d07..5ee7ff3fc4 100644
--- a/crates/ty/tests/cli/main.rs
+++ b/crates/ty/tests/cli/main.rs
@@ -275,7 +275,7 @@ fn cli_arguments_are_relative_to_the_current_directory() -> anyhow::Result<()> {
     WARN ty is pre-release software and not ready for production use. Expect to encounter bugs, missing features, and fatal errors.
     ");
 
-    assert_cmd_snapshot!(case.command().current_dir(case.root().join("child")).arg("--extra-search-path").arg("../libs"), @r"
+    assert_cmd_snapshot!(case.command().current_dir(case.root().join("child")).arg("--non-environment-search-path").arg("../libs"), @r"
     success: true
     exit_code: 0
     ----- stdout -----
@@ -290,7 +290,7 @@ fn cli_arguments_are_relative_to_the_current_directory() -> anyhow::Result<()> {
 
 /// Paths specified in a configuration file are relative to the project root.
 ///
-/// We test this by adding `libs` (as a relative path) to the extra search path in the configuration and run
+/// We test this by adding `libs` (as a relative path) to `non-environment-paths` in the configuration and run
 /// the CLI from a subdirectory.
 ///
 /// Project layout:
@@ -309,7 +309,7 @@ fn paths_in_configuration_files_are_relative_to_the_project_root() -> anyhow::Re
             r#"
             [tool.ty.environment]
             python-version = "3.11"
-            extra-paths = ["libs"]
+            non-environment-paths = ["libs"]
             "#,
         ),
         (
diff --git a/crates/ty/tests/file_watching.rs b/crates/ty/tests/file_watching.rs
index 950cf82a84..cdf2933fe9 100644
--- a/crates/ty/tests/file_watching.rs
+++ b/crates/ty/tests/file_watching.rs
@@ -422,7 +422,7 @@ where
     // We need a chance to create the directories here.
     if let Some(environment) = project.options().environment.as_ref() {
         for path in environment
-            .extra_paths
+            .non_environment_paths
             .as_deref()
             .unwrap_or_default()
             .iter()
@@ -542,7 +542,7 @@ fn new_non_project_file() -> anyhow::Result<()> {
         context.write_project_file("bar.py", "")?;
         context.set_options(Options {
             environment: Some(EnvironmentOptions {
-                extra_paths: Some(vec![RelativePathBuf::cli(
+                non_environment_paths: Some(vec![RelativePathBuf::cli(
                     context.join_root_path("site_packages"),
                 )]),
                 ..EnvironmentOptions::default()
@@ -986,7 +986,7 @@ fn search_path() -> anyhow::Result<()> {
 
         context.set_options(Options {
             environment: Some(EnvironmentOptions {
-                extra_paths: Some(vec![RelativePathBuf::cli(
+                non_environment_paths: Some(vec![RelativePathBuf::cli(
                     context.join_root_path("site_packages"),
                 )]),
                 ..EnvironmentOptions::default()
@@ -1027,7 +1027,7 @@ fn add_search_path() -> anyhow::Result<()> {
     // Register site-packages as a search path.
     case.update_options(Options {
         environment: Some(EnvironmentOptions {
-            extra_paths: Some(vec![RelativePathBuf::cli("site_packages")]),
+            non_environment_paths: Some(vec![RelativePathBuf::cli("site_packages")]),
             ..EnvironmentOptions::default()
         }),
         ..Options::default()
@@ -1051,7 +1051,7 @@ fn remove_search_path() -> anyhow::Result<()> {
         context.write_project_file("bar.py", "import sub.a")?;
         context.set_options(Options {
             environment: Some(EnvironmentOptions {
-                extra_paths: Some(vec![RelativePathBuf::cli(
+                non_environment_paths: Some(vec![RelativePathBuf::cli(
                     context.join_root_path("site_packages"),
                 )]),
                 ..EnvironmentOptions::default()
@@ -1579,7 +1579,7 @@ mod unix {
 
             context.set_options(Options {
                 environment: Some(EnvironmentOptions {
-                    extra_paths: Some(vec![RelativePathBuf::cli(
+                    non_environment_paths: Some(vec![RelativePathBuf::cli(
                         ".venv/lib/python3.12/site-packages",
                     )]),
                     python_version: Some(RangedValue::cli(PythonVersion::PY312)),
diff --git a/crates/ty_combine/src/lib.rs b/crates/ty_combine/src/lib.rs
index d2033cadd5..e4daf4db80 100644
--- a/crates/ty_combine/src/lib.rs
+++ b/crates/ty_combine/src/lib.rs
@@ -32,25 +32,25 @@ use ty_python_semantic::PythonPlatform;
 ///
 /// The main downside of this approach is that the ordering can be surprising in cases
 /// where the option has a "first match" semantic and not a "last match" wins.
-/// One such example is `extra-paths` where the semantics is given by Python:
+/// One such example is `non-environment-paths` where the semantics is given by Python:
 /// the module on the first matching search path wins.
 ///
 /// ```toml
 /// [environment]
-/// extra-paths = ["b", "c"]
+/// non-environment-paths = ["b", "c"]
 /// ```
 ///
 /// ```bash
-/// ty --extra-paths a
+/// ty --non-environment-search-path=a
 /// ```
 ///
 /// That's why a user might expect that this configuration results in `["a", "b", "c"]`,
 /// because the CLI has higher precedence. However, the current implementation results in a
-/// resolved extra search path of `["b", "c", "a"]`, which means `a` will be tried last.
+/// resolved `non-environment-paths` of `["b", "c", "a"]`, which means `a` will be tried last.
 ///
 /// There's an argument here that the user should be able to specify the order of the paths,
-/// because only then is the user in full control of where to insert the path when specifying `extra-paths`
-/// in multiple sources.
+/// because only then is the user in full control of where to insert the path when specifying
+/// `non-environment-paths` in multiple sources.
 ///
 /// ## Macro
 /// You can automatically derive `Combine` for structs with named fields by using `derive(ruff_macros::Combine)`.
diff --git a/crates/ty_project/src/metadata/options.rs b/crates/ty_project/src/metadata/options.rs
index 36709174df..07c5d61275 100644
--- a/crates/ty_project/src/metadata/options.rs
+++ b/crates/ty_project/src/metadata/options.rs
@@ -301,18 +301,19 @@ impl Options {
         };
 
         // collect the existing site packages
-        let mut extra_paths: Vec<SystemPathBuf> = environment
-            .extra_paths
+        let mut non_environment_paths: Vec<SystemPathBuf> = environment
+            .non_environment_paths
             .as_deref()
             .unwrap_or_default()
             .iter()
             .map(|path| path.absolute(project_root, system))
             .collect();
 
-        // read all the paths off the PYTHONPATH environment variable, check
-        // they exist as a directory, and add them to the vec of extra_paths
-        // as they should be checked before site-packages just like python
-        // interpreter does
+        // Read all the paths off the `PYTHONPATH` environment variable, check
+        // each exists as a directory, and add each to the vec of `non_environment_paths`.
+        // This emulates the way `PYTHONPATH` entries will appear in `sys.path` prior to
+        // `site-packages` (the "environment search path") from a virtual environment at
+        // runtime.
         if let Ok(python_path) = system.env_var(EnvVars::PYTHONPATH) {
             for path in std::env::split_paths(python_path.as_str()) {
                 let path = match SystemPathBuf::from_path_buf(path) {
@@ -336,15 +337,15 @@ impl Options {
                 }
 
                 tracing::debug!(
-                    "Adding `{abspath}` from the `PYTHONPATH` environment variable to `extra_paths`"
+                    "Adding `{abspath}` from the `PYTHONPATH` environment variable to `non_environment_paths`"
                 );
 
-                extra_paths.push(abspath);
+                non_environment_paths.push(abspath);
             }
         }
 
         let settings = SearchPathSettings {
-            extra_paths,
+            non_environment_paths,
             src_roots,
             custom_typeshed: environment
                 .typeshed
@@ -563,10 +564,10 @@ pub struct EnvironmentOptions {
         default = r#"[]"#,
         value_type = "list[str]",
         example = r#"
-            extra-paths = ["./shared/my-search-path"]
+            non-environment-paths = ["./shared/my-search-path"]
         "#
     )]
-    pub extra_paths: Option<Vec<RelativePathBuf>>,
+    pub non_environment_paths: Option<Vec<RelativePathBuf>>,
 
     /// Optional path to a "typeshed" directory on disk for us to use for standard-library types.
     /// If this is not provided, we will fallback to our vendored typeshed stubs for the stdlib,
diff --git a/crates/ty_project/src/metadata/value.rs b/crates/ty_project/src/metadata/value.rs
index 95a157a451..4c65c37066 100644
--- a/crates/ty_project/src/metadata/value.rs
+++ b/crates/ty_project/src/metadata/value.rs
@@ -25,7 +25,7 @@ pub enum ValueSource {
     File(Arc<SystemPathBuf>),
 
     /// The value comes from a CLI argument, while it's left open if specified using a short argument,
-    /// long argument (`--extra-paths`) or `--config key=value`.
+    /// long argument (`--non-environment-search-path`) or `--config key=value`.
     Cli,
 
     /// The value comes from an LSP client configuration.
diff --git a/crates/ty_python_semantic/resources/mdtest/import/case_sensitive.md b/crates/ty_python_semantic/resources/mdtest/import/case_sensitive.md
index f822ba47e2..ed64f214a2 100644
--- a/crates/ty_python_semantic/resources/mdtest/import/case_sensitive.md
+++ b/crates/ty_python_semantic/resources/mdtest/import/case_sensitive.md
@@ -48,7 +48,7 @@ search paths if the file name's casing does not match.
 
 ```toml
 [environment]
-extra-paths = ["/search-1", "/search-2"]
+non-environment-paths = ["/search-1", "/search-2"]
 ```
 
 `/search-1/A.py`:
diff --git a/crates/ty_python_semantic/resources/mdtest/import/partial_stub_packages.md b/crates/ty_python_semantic/resources/mdtest/import/partial_stub_packages.md
index a609c998b3..3538a587b7 100644
--- a/crates/ty_python_semantic/resources/mdtest/import/partial_stub_packages.md
+++ b/crates/ty_python_semantic/resources/mdtest/import/partial_stub_packages.md
@@ -40,7 +40,7 @@ neither.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/py.typed`:
@@ -99,7 +99,7 @@ Omitting the partial `py.typed`, we see "impl" now cannot be found.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/__init__.pyi`:
@@ -152,7 +152,7 @@ Including a blank py.typed we still don't conclude it's partial.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/py.typed`:
@@ -210,7 +210,7 @@ reveal_type(Fake().fake)  # revealed: Unknown
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/py.typed`:
@@ -280,7 +280,7 @@ reveal_type(Fake().fake)  # revealed: Unknown
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/py.typed`:
@@ -355,7 +355,7 @@ reveal_type(Fake().fake)  # revealed: Unknown
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/py.typed`:
@@ -433,7 +433,7 @@ This is a regression test for <https://github.com/astral-sh/ty/issues/520>.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/parent-stubs/foo/both.pyi`:
diff --git a/crates/ty_python_semantic/resources/mdtest/import/stub_packages.md b/crates/ty_python_semantic/resources/mdtest/import/stub_packages.md
index 3f99e5d92b..33b5a0f9dc 100644
--- a/crates/ty_python_semantic/resources/mdtest/import/stub_packages.md
+++ b/crates/ty_python_semantic/resources/mdtest/import/stub_packages.md
@@ -7,7 +7,7 @@ Stub packages are packages named `<package>-stubs` that provide typing stubs for
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/__init__.pyi`:
@@ -38,7 +38,7 @@ The regular package isn't required for type checking.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs/__init__.pyi`:
@@ -63,7 +63,7 @@ A module named `<module>-stubs` isn't a stub package.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/foo-stubs.pyi`:
@@ -88,7 +88,7 @@ A namespace package with multiple stub packages spread over multiple search path
 
 ```toml
 [environment]
-extra-paths = ["/stubs1", "/stubs2", "/packages"]
+non-environment-paths = ["/stubs1", "/stubs2", "/packages"]
 ```
 
 `/stubs1/shapes-stubs/polygons/pentagon.pyi`:
@@ -136,7 +136,7 @@ should stop after the first non-namespace stub package. This matches Pyright's b
 
 ```toml
 [environment]
-extra-paths = ["/stubs1", "/stubs2", "/packages"]
+non-environment-paths = ["/stubs1", "/stubs2", "/packages"]
 ```
 
 `/stubs1/shapes-stubs/__init__.pyi`:
@@ -196,7 +196,7 @@ fewer lookups.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/shapes-stubs/polygons/pentagon.pyi`:
@@ -254,7 +254,7 @@ to be an enforced convention. At least, Pyright is fine with the following.
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/shapes-stubs/__init__.py`:
@@ -291,7 +291,7 @@ Regression test for <https://github.com/astral-sh/ty/issues/408>
 
 ```toml
 [environment]
-extra-paths = ["/packages"]
+non-environment-paths = ["/packages"]
 ```
 
 `/packages/yaml-stubs/__init__.pyi`:
diff --git a/crates/ty_python_semantic/src/module_resolver/path.rs b/crates/ty_python_semantic/src/module_resolver/path.rs
index cb524cb4ac..b2c90e0308 100644
--- a/crates/ty_python_semantic/src/module_resolver/path.rs
+++ b/crates/ty_python_semantic/src/module_resolver/path.rs
@@ -93,7 +93,7 @@ impl ModulePath {
             relative_path,
         } = self;
         match &*search_path.0 {
-            SearchPathInner::Extra(search_path)
+            SearchPathInner::NonEnvironment(search_path)
             | SearchPathInner::FirstParty(search_path)
             | SearchPathInner::SitePackages(search_path)
             | SearchPathInner::Editable(search_path)
@@ -131,7 +131,7 @@ impl ModulePath {
         } = self;
 
         match &*search_path.0 {
-            SearchPathInner::Extra(search_path)
+            SearchPathInner::NonEnvironment(search_path)
             | SearchPathInner::FirstParty(search_path)
             | SearchPathInner::SitePackages(search_path)
             | SearchPathInner::Editable(search_path) => {
@@ -199,7 +199,7 @@ impl ModulePath {
             relative_path,
         } = self;
         match &*search_path.0 {
-            SearchPathInner::Extra(search_path)
+            SearchPathInner::NonEnvironment(search_path)
             | SearchPathInner::FirstParty(search_path)
             | SearchPathInner::SitePackages(search_path)
             | SearchPathInner::Editable(search_path) => Some(search_path.join(relative_path)),
@@ -219,7 +219,7 @@ impl ModulePath {
             relative_path,
         } = self;
         match &*search_path.0 {
-            SearchPathInner::Extra(search_path)
+            SearchPathInner::NonEnvironment(search_path)
             | SearchPathInner::FirstParty(search_path)
             | SearchPathInner::SitePackages(search_path)
             | SearchPathInner::Editable(search_path) => {
@@ -451,7 +451,7 @@ type SearchPathResult<T> = Result<T, SearchPathValidationError>;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash, get_size2::GetSize)]
 enum SearchPathInner {
-    Extra(SystemPathBuf),
+    NonEnvironment(SystemPathBuf),
     FirstParty(SystemPathBuf),
     StandardLibraryCustom(SystemPathBuf),
     StandardLibraryVendored(VendoredPathBuf),
@@ -464,7 +464,7 @@ enum SearchPathInner {
 /// that can be used to locate Python modules.
 ///
 /// The different kinds of search paths are:
-/// - "Extra" search paths: these go at the start of the module resolution order
+/// - "Non-environment" search paths: these go at the start of the module resolution order
 /// - First-party search paths: the user code that we are directly invoked on.
 /// - Standard-library search paths: these come in three different forms:
 ///   - Custom standard-library search paths: paths provided by the user
@@ -499,9 +499,12 @@ impl SearchPath {
         }
     }
 
-    /// Create a new "Extra" search path
-    pub(crate) fn extra(system: &dyn System, root: SystemPathBuf) -> SearchPathResult<Self> {
-        Ok(Self(Arc::new(SearchPathInner::Extra(
+    /// Create a new non-environment search path
+    pub(crate) fn non_environment(
+        system: &dyn System,
+        root: SystemPathBuf,
+    ) -> SearchPathResult<Self> {
+        Ok(Self(Arc::new(SearchPathInner::NonEnvironment(
             Self::directory_path(system, root)?,
         ))))
     }
@@ -616,7 +619,7 @@ impl SearchPath {
         }
 
         match &*self.0 {
-            SearchPathInner::Extra(search_path)
+            SearchPathInner::NonEnvironment(search_path)
             | SearchPathInner::FirstParty(search_path)
             | SearchPathInner::StandardLibraryCustom(search_path)
             | SearchPathInner::StandardLibraryReal(search_path)
@@ -643,7 +646,7 @@ impl SearchPath {
         }
 
         match &*self.0 {
-            SearchPathInner::Extra(_)
+            SearchPathInner::NonEnvironment(_)
             | SearchPathInner::FirstParty(_)
             | SearchPathInner::StandardLibraryCustom(_)
             | SearchPathInner::StandardLibraryReal(_)
@@ -662,7 +665,7 @@ impl SearchPath {
     #[must_use]
     pub(super) fn as_path(&self) -> SystemOrVendoredPathRef<'_> {
         match *self.0 {
-            SearchPathInner::Extra(ref path)
+            SearchPathInner::NonEnvironment(ref path)
             | SearchPathInner::FirstParty(ref path)
             | SearchPathInner::StandardLibraryCustom(ref path)
             | SearchPathInner::StandardLibraryReal(ref path)
@@ -691,7 +694,7 @@ impl SearchPath {
     #[must_use]
     pub(crate) fn debug_kind(&self) -> &'static str {
         match *self.0 {
-            SearchPathInner::Extra(_) => "extra",
+            SearchPathInner::NonEnvironment(_) => "extra",
             SearchPathInner::FirstParty(_) => "first-party",
             SearchPathInner::StandardLibraryCustom(_) => "std-custom",
             SearchPathInner::StandardLibraryReal(_) => "std-real",
@@ -706,8 +709,8 @@ impl SearchPath {
     #[must_use]
     pub(crate) fn describe_kind(&self) -> &'static str {
         match *self.0 {
-            SearchPathInner::Extra(_) => {
-                "extra search path specified on the CLI or in your config file"
+            SearchPathInner::NonEnvironment(_) => {
+                "non-environment search path specified on the CLI or in your config file"
             }
             SearchPathInner::FirstParty(_) => "first-party code",
             SearchPathInner::StandardLibraryCustom(_) => {
@@ -772,7 +775,7 @@ impl PartialEq<SearchPath> for VendoredPathBuf {
 impl fmt::Display for SearchPath {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match &*self.0 {
-            SearchPathInner::Extra(system_path_buf)
+            SearchPathInner::NonEnvironment(system_path_buf)
             | SearchPathInner::FirstParty(system_path_buf)
             | SearchPathInner::SitePackages(system_path_buf)
             | SearchPathInner::Editable(system_path_buf)
@@ -1073,7 +1076,7 @@ mod tests {
     fn relativize_non_stdlib_path_errors() {
         let TestCase { db, src, .. } = TestCaseBuilder::new().build();
 
-        let root = SearchPath::extra(db.system(), src.clone()).unwrap();
+        let root = SearchPath::non_environment(db.system(), src.clone()).unwrap();
         // Must have a `.py` extension, a `.pyi` extension, or no extension:
         let bad_absolute_path = src.join("x.rs");
         assert_eq!(root.relativize_system_path(&bad_absolute_path), None);
diff --git a/crates/ty_python_semantic/src/module_resolver/resolver.rs b/crates/ty_python_semantic/src/module_resolver/resolver.rs
index f4cb91e28f..40af558f2f 100644
--- a/crates/ty_python_semantic/src/module_resolver/resolver.rs
+++ b/crates/ty_python_semantic/src/module_resolver/resolver.rs
@@ -228,7 +228,7 @@ impl SearchPaths {
         }
 
         let SearchPathSettings {
-            extra_paths,
+            non_environment_paths,
             src_roots,
             custom_typeshed: typeshed,
             site_packages_paths,
@@ -237,11 +237,11 @@ impl SearchPaths {
 
         let mut static_paths = vec![];
 
-        for path in extra_paths {
+        for path in non_environment_paths {
             let path = canonicalize(path, system);
-            tracing::debug!("Adding extra search-path `{path}`");
+            tracing::debug!("Adding non-environment search path `{path}`");
 
-            static_paths.push(SearchPath::extra(system, path)?);
+            static_paths.push(SearchPath::non_environment(system, path)?);
         }
 
         for src_root in src_roots {
diff --git a/crates/ty_python_semantic/src/program.rs b/crates/ty_python_semantic/src/program.rs
index 8f06527951..4f2441caf1 100644
--- a/crates/ty_python_semantic/src/program.rs
+++ b/crates/ty_python_semantic/src/program.rs
@@ -110,7 +110,7 @@ pub enum PythonVersionSource {
     InstallationDirectoryLayout { site_packages_parent_dir: Box<str> },
 
     /// The value comes from a CLI argument, while it's left open if specified using a short argument,
-    /// long argument (`--extra-paths`) or `--config key=value`.
+    /// long argument (`--non-environment-search-path`) or `--config key=value`.
     Cli,
 
     /// The value comes from the Python VS Code extension (the selected interpreter).
@@ -163,10 +163,10 @@ impl Default for PythonVersionWithSource {
 /// Configures the search paths for module resolution.
 #[derive(Eq, PartialEq, Debug, Clone)]
 pub struct SearchPathSettings {
-    /// List of user-provided paths that should take first priority in the module resolution.
-    /// Examples in other type checkers are mypy's MYPYPATH environment variable,
-    /// or pyright's stubPath configuration setting.
-    pub extra_paths: Vec<SystemPathBuf>,
+    /// List of user-provided paths that should take first priority in module resolution.
+    /// Examples in other type checkers are mypy's `MYPYPATH` environment variable,
+    /// or pyright's `stubPath` configuration setting.
+    pub non_environment_paths: Vec<SystemPathBuf>,
 
     /// The root of the project, used for finding first-party modules.
     pub src_roots: Vec<SystemPathBuf>,
@@ -197,7 +197,7 @@ impl SearchPathSettings {
     pub fn empty() -> Self {
         SearchPathSettings {
             src_roots: vec![],
-            extra_paths: vec![],
+            non_environment_paths: vec![],
             custom_typeshed: None,
             site_packages_paths: vec![],
             real_stdlib_path: None,
diff --git a/crates/ty_test/src/config.rs b/crates/ty_test/src/config.rs
index bc32678449..f0eae9c47e 100644
--- a/crates/ty_test/src/config.rs
+++ b/crates/ty_test/src/config.rs
@@ -44,8 +44,8 @@ impl MarkdownTestConfig {
         self.environment.as_ref()?.typeshed.as_deref()
     }
 
-    pub(crate) fn extra_paths(&self) -> Option<&[SystemPathBuf]> {
-        self.environment.as_ref()?.extra_paths.as_deref()
+    pub(crate) fn non_environment_paths(&self) -> Option<&[SystemPathBuf]> {
+        self.environment.as_ref()?.non_environment_paths.as_deref()
     }
 
     pub(crate) fn python(&self) -> Option<&SystemPath> {
@@ -75,7 +75,7 @@ pub(crate) struct Environment {
     pub(crate) typeshed: Option<SystemPathBuf>,
 
     /// Additional search paths to consider when resolving modules.
-    pub(crate) extra_paths: Option<Vec<SystemPathBuf>>,
+    pub(crate) non_environment_paths: Option<Vec<SystemPathBuf>>,
 
     /// Path to the Python environment.
     ///
diff --git a/crates/ty_test/src/lib.rs b/crates/ty_test/src/lib.rs
index 8b03002b20..530f9d5349 100644
--- a/crates/ty_test/src/lib.rs
+++ b/crates/ty_test/src/lib.rs
@@ -303,7 +303,10 @@ fn run_test(
             .unwrap_or(PythonPlatform::Identifier("linux".to_string())),
         search_paths: SearchPathSettings {
             src_roots: vec![src_path],
-            extra_paths: configuration.extra_paths().unwrap_or_default().to_vec(),
+            non_environment_paths: configuration
+                .non_environment_paths()
+                .unwrap_or_default()
+                .to_vec(),
             custom_typeshed: custom_typeshed_path.map(SystemPath::to_path_buf),
             site_packages_paths,
             real_stdlib_path: None,
diff --git a/ty.schema.json b/ty.schema.json
index b8c5fcbef2..25954da82d 100644
--- a/ty.schema.json
+++ b/ty.schema.json
@@ -61,7 +61,7 @@
     "EnvironmentOptions": {
       "type": "object",
       "properties": {
-        "extra-paths": {
+        "non-environment-paths": {
           "description": "User-provided paths that should take first priority in module resolution.\n\nThis is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use the `python` option to specify the location of your Python environment.\n\nThis option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath` configuration setting.",
           "type": [
             "array",