From 4b373b20709eb5314510aca3ae9e4e62b999a64d Mon Sep 17 00:00:00 2001
From: Ozawa Song <139314449+dawid0309@users.noreply.github.com>
Date: Wed, 28 Oct 2026 00:29:22 +0800
Subject: [PATCH] fix(python)!: support compat-only imports (#3973)

Read `__version__` from the native `_lancedb` module so `import lancedb`
works when only `lancedb-compat` is installed. Add the type declaration
and a subprocess regression test.

Ruff and Linux-targeted Pyright pass. Import tests: 1 passed and 1
Linux-only test skipped on Windows. Runtime tests used the official
same-version Windows native module; a fresh source build still needs CI.

BREAKING CHANGE: `lancedb.__version__` now uses the native version
string.
Prereleases may report `0.41.0-beta.13` instead of `0.41.0b13`.

Fixes #3950

---------

Co-authored-by: Xuanwo <github@xuanwo.io>
---
 python/python/lancedb/__init__.py  |  4 +---
 python/python/lancedb/_lancedb.pyi |  1 +
 python/python/tests/test_import.py | 34 ++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/python/python/lancedb/__init__.py b/python/python/lancedb/__init__.py
index 6c71c6261..fa1c105e9 100644
--- a/python/python/lancedb/__init__.py
+++ b/python/python/lancedb/__init__.py
@@ -2,14 +2,12 @@
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors
 
 
-import importlib.metadata
 import os
 from concurrent.futures import ThreadPoolExecutor
 from datetime import timedelta
 from typing import Dict, Optional, Union, Any, List, Iterable, TYPE_CHECKING
 
-__version__ = importlib.metadata.version("lancedb")
-
+from ._lancedb import __version__ as __version__
 from ._lancedb import connect as lancedb_connect
 from ._lancedb import FtsToken
 from ._lancedb import FunctionErrorFragment as FunctionErrorFragment
diff --git a/python/python/lancedb/_lancedb.pyi b/python/python/lancedb/_lancedb.pyi
index 7e1307a4a..d5fcac30f 100644
--- a/python/python/lancedb/_lancedb.pyi
+++ b/python/python/lancedb/_lancedb.pyi
@@ -32,6 +32,7 @@ IvfHnswPq: type[HnswPq] = HnswPq
 IvfHnswSq: type[HnswSq] = HnswSq
 IvfHnswFlat: type[HnswFlat] = HnswFlat
 AnalyzePlanDistributedMetrics = Literal["aggregate", "per_worker", "full"]
+__version__: str
 
 class MetricPoint:
     name: str
diff --git a/python/python/tests/test_import.py b/python/python/tests/test_import.py
index 4b87a0ce8..e8373b03b 100644
--- a/python/python/tests/test_import.py
+++ b/python/python/tests/test_import.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors
 
+import os
 import re
 import shutil
 import subprocess
@@ -31,3 +32,36 @@ def test_native_extension_does_not_link_openssl():
         "the LanceDB native extension must use rustls instead of linking OpenSSL: "
         f"{openssl_libraries}"
     )
+
+
+def test_top_level_version_comes_from_native_module():
+    child_code = """
+import importlib.metadata
+
+orig_version = importlib.metadata.version
+
+def fail_version_lookup(_: str) -> str:
+    if _ in {"lancedb", "lancedb-compat"}:
+        raise AssertionError("lancedb import should not query distribution metadata")
+    return orig_version(_)
+
+importlib.metadata.version = fail_version_lookup
+
+import lancedb
+import lancedb._lancedb as native_module
+import lancedb.db
+
+assert lancedb.__version__ == native_module.__version__
+"""
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join(path for path in sys.path if path)
+
+    result = subprocess.run(
+        [sys.executable, "-c", child_code],
+        check=False,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+    assert result.returncode == 0, result.stderr or result.stdout