slide2vec 6.0.0__tar.gz → 6.1.0__tar.gz

{slide2vec-6.0.0 → slide2vec-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.0.0
+Version: 6.1.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,7 @@ Requires-Dist: numpy<2; extra == "fm"
 Requires-Dist: pandas; extra == "fm"
 Requires-Dist: pillow; extra == "fm"
 Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"

{slide2vec-6.0.0 → slide2vec-6.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "6.0.0"
+version = "6.1.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -100,7 +100,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -149,7 +149,7 @@ zip-safe = false
 include = ["slide2vec*"]
 
 [tool.setuptools.package-data]
-slide2vec = ["py.typed"]
+slide2vec = ["py.typed", "cufile.json"]
 "slide2vec.configs" = ["*.yaml", "models/*.yaml", "preprocessing/*.yaml"]
 
 [tool.pytest.ini_options]
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "6.0.0"
+current_version = "6.1.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/__init__.py

@@ -1,3 +1,7 @@
+from slide2vec._cufile import disable_cufile_compat_mode
+
+disable_cufile_compat_mode()  # Before anything can import cucim.
+
 from slide2vec.api import (
     DenseImageOptions,
     DenseOptions,
@@ -27,7 +31,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "6.0.0"
+__version__ = "6.1.0"
 
 __all__ = [
     "Model",

slide2vec-6.1.0/slide2vec/_cufile.py

@@ -0,0 +1,21 @@
+"""Keep ``import cucim`` from opening a CUDA context on every visible GPU (issue #326).
+
+cuCIM opens the cuFile (GPUDirect Storage) driver when it is imported. Without the
+``nvidia-fs`` kernel module the driver falls back to "compat mode", which still creates a
+~520 MiB CUDA context on each visible device although every read then goes through plain
+POSIX I/O. Pointing cuFile at a config that disallows compat mode makes the driver open fail
+instead: cuCIM reads through POSIX exactly as before, and no context is created. Where
+``nvidia-fs`` is loaded the driver opens as usual and GDS keeps working.
+
+cuFile reads ``CUFILE_ENV_PATH_JSON`` once, when cuCIM is imported, so this must run before
+that import: ``slide2vec/__init__.py`` calls it first. A value the user already set wins.
+"""
+
+import os
+from pathlib import Path
+
+CUFILE_ENV = "CUFILE_ENV_PATH_JSON"
+
+
+def disable_cufile_compat_mode(environ=os.environ) -> None:
+    environ.setdefault(CUFILE_ENV, str(Path(__file__).with_name("cufile.json")))

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/api.py

@@ -145,13 +145,18 @@ class PreprocessingConfig:
 
     #: Slide reading backend. ``"auto"`` tries cucim → vips → openslide → asap.
     #: Explicit choices: ``"cucim"``, ``"openslide"``, ``"vips"``, ``"asap"``.
+    #: Slides without spacing metadata require ``spacing_at_level_0``, including
+    #: untagged TIFFs read with VIPS.
     backend: str = "auto"
-    #: Source-mask reading backend, resolved independently from the *mask* path
-    #: (hs2p ≥ 4.3.0). ``"auto"`` probes openability just like :attr:`backend`. Set this
+    #: Source-mask reading backend, resolved independently from the *mask* path.
+    #: ``"auto"`` probes openability just like :attr:`backend`. Set this
     #: explicitly (e.g. ``"openslide"``) when a precomputed tissue or annotation mask needs
     #: a different decoder than its slide — hs2p no longer silently falls back to another
     #: reader, so a mask the slide backend cannot decode fails unless overridden here.
-    #: Accepts the same values as :attr:`backend`; ignored for slides with no source mask.
+    #: Accepts the same values as :attr:`backend` plus ``"pil"`` for PNG/JPEG masks;
+    #: ``"auto"`` selects PIL for these masks. Ignored for slides with no source mask.
+    #: Masks need no spacing metadata, but must align to the slide's field of view and
+    #: contain only declared label IDs. See :doc:`preprocessing` for hs2p 5 validation.
     mask_backend: str = "auto"
     #: Target spacing in µm/px. Resolved from the model preset when ``None``.
     requested_spacing_um: float | None = None

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/configs/default.yaml

@@ -36,7 +36,7 @@ tiling:
     # where `mask_path` is read as a multi-label raster. The `tissue` min_coverage entry below is
     # the single source of truth for the tissue threshold.
     output_mode: per_annotation # how sampled tiles are grouped into artifacts. per_annotation: one flat artifact set per sampled class, namespaced under a `<class>/` subdir (the `tissue` class collapses to the flat root). merged: a single flat artifact set per slide over the union of tiles passing any active class threshold — it carries no class label, so it lands at the flat output root (no `<class>/` subdir).
-    pixel_mapping: # {class_name: integer pixel value in the mask raster}
+    pixel_mapping: # {class_name: integer pixel value in the mask raster}; a list (e.g. tumor: [2, 3]) merges several values into one class; every mask value must be declared
       background: 0
       tissue: 1
     colors: # {class_name: [r, g, b] | null} used when rendering previews

slide2vec-6.1.0/slide2vec/cufile.json

@@ -0,0 +1,5 @@
+{
+    "properties": {
+        "allow_compat_mode": false
+    }
+}

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/distributed/__init__.py

@@ -2,6 +2,8 @@ import os
 
 import torch
 
+from slide2vec.distributed.worker_entry import PINNED_ENV
+
 _RANK = -1
 _WORLD_SIZE = -1
 _LOCAL_RANK = -1
@@ -43,6 +45,19 @@ def get_local_rank() -> int:
     return _LOCAL_RANK
 
 
+def get_device_ordinal() -> int:
+    """
+    Returns:
+        The CUDA ordinal of this process's GPU: 0 once :mod:`slide2vec.distributed.pin_gpu`
+        has left it the only visible device, else the local rank.
+    """
+    return _device_ordinal(get_local_rank())
+
+
+def _device_ordinal(local_rank: int) -> int:
+    return 0 if os.environ.get(PINNED_ENV) == "1" else local_rank
+
+
 def get_local_size() -> int:
     """
     Returns:
@@ -181,7 +196,7 @@ def enable(
 
     Args:
         set_cuda_current_device: If True, call torch.cuda.set_device() to set the
-            current PyTorch CUDA device to the one matching the local rank.
+            current PyTorch CUDA device to this rank's GPU (see get_device_ordinal()).
         overwrite: If True, overwrites already set variables. Else fails.
     """
 
@@ -192,7 +207,7 @@ def enable(
     torch_env.export(overwrite=overwrite)
 
     if set_cuda_current_device:
-        torch.cuda.set_device(torch_env.local_rank)
+        torch.cuda.set_device(_device_ordinal(torch_env.local_rank))
 
     _RANK = torch_env.rank
     _WORLD_SIZE = torch_env.world_size

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/distributed/direct_embed_worker.py

@@ -42,7 +42,7 @@ def main(argv=None) -> int:
     model_spec = dict(request["model"])
     model = Model.from_preset(
         model_spec["name"],
-        device=f"cuda:{local_rank}",
+        device=f"cuda:{distributed.get_device_ordinal()}",
         output_variant=model_spec.get("output_variant"),
         allow_non_recommended_settings=bool(model_spec["allow_non_recommended_settings"]),
     )

slide2vec-6.1.0/slide2vec/distributed/pin_gpu.py

@@ -0,0 +1,47 @@
+"""Bootstrap that shows a torchrun worker only its own GPU, then runs the worker (issue #326).
+
+``import cucim`` opens a CUDA context on every visible device, so a rank that can see its
+siblings' GPUs holds an idle context on each of them. CUDA reads ``CUDA_VISIBLE_DEVICES``
+once, when it initialises, and ``import slide2vec`` already initialises it (``transformers``
+calls ``torch.cuda.is_available()`` at import). A worker module therefore cannot narrow its
+own visibility: ``python -m slide2vec.distributed.<worker>`` has imported the package before
+the worker's first line runs. torchrun runs this file **by path** instead, so the narrowing
+happens before anything is imported. Keep this file free of slide2vec and torch imports.
+
+Only for workers that run no collectives: a pinned rank cannot see its siblings' GPUs.
+
+Usage: ``torchrun ... pin_gpu.py <worker module> [worker args...]``
+"""
+
+import os
+import runpy
+import sys
+
+PINNED_ENV = "SLIDE2VEC_WORKER_GPU_PINNED"  # Mirrored in worker_entry.PINNED_ENV.
+
+
+def pin_to_own_gpu(environ) -> None:
+    """Narrow ``CUDA_VISIBLE_DEVICES`` to the ``LOCAL_RANK``-th GPU this process inherited."""
+    local_rank = int(environ["LOCAL_RANK"])
+    visible = [gpu.strip() for gpu in environ.get("CUDA_VISIBLE_DEVICES", "").split(",") if gpu.strip()]
+    if visible and local_rank >= len(visible):
+        raise RuntimeError(
+            f"LOCAL_RANK={local_rank} but CUDA_VISIBLE_DEVICES lists only {len(visible)} GPU(s)"
+        )
+    environ["CUDA_VISIBLE_DEVICES"] = visible[local_rank] if visible else str(local_rank)
+    environ[PINNED_ENV] = "1"
+
+
+def main() -> None:
+    pin_to_own_gpu(os.environ)
+    module, *worker_args = sys.argv[1:]
+    # Prefer the package that supplied this bootstrap over a competing checkout in cwd.
+    # Keep cwd importable without changing how relative data and output paths resolve.
+    package_root = os.path.realpath(os.path.join(os.path.dirname(__file__), "..", ".."))
+    sys.path[:1] = [package_root, os.getcwd()]
+    sys.argv = [module, *worker_args]
+    runpy.run_module(module, run_name="__main__", alter_sys=True)
+
+
+if __name__ == "__main__":
+    main()

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/distributed/pipeline_worker.py

@@ -36,7 +36,7 @@ def main(argv=None) -> int:
     model_spec = dict(request["model"])
     model = Model.from_preset(
         model_spec["name"],
-        device=f"cuda:{local_rank}",
+        device=f"cuda:{distributed.get_device_ordinal()}",
         output_variant=model_spec.get("output_variant"),
         allow_non_recommended_settings=bool(model_spec["allow_non_recommended_settings"]),
     )

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/distributed/worker_entry.py

@@ -18,6 +18,10 @@ from contextlib import nullcontext
 from dataclasses import dataclass
 
 
+#: Set by :mod:`slide2vec.distributed.pin_gpu` once this process sees only its own GPU.
+PINNED_ENV = "SLIDE2VEC_WORKER_GPU_PINNED"
+
+
 @dataclass(frozen=True, kw_only=True)
 class WorkerRank:
     """This process's place in the torchrun world: which shard, and which GPU."""
@@ -26,12 +30,14 @@ class WorkerRank:
     global_rank: int
     #: Number of shards the work list is cut into.
     world_size: int
-    #: Local device ordinal, i.e. ``cuda:<local_rank>``.
+    #: This process's index among the ranks on its node; names it in progress labels.
     local_rank: int
+    #: CUDA ordinal of this rank's GPU: 0 once the process is pinned to it, else ``local_rank``.
+    device_ordinal: int
 
     @property
     def device(self) -> str:
-        return f"cuda:{self.local_rank}"
+        return f"cuda:{self.device_ordinal}"
 
 
 def worker_args_parser(module: str, *, add_help: bool = True) -> argparse.ArgumentParser:
@@ -46,12 +52,15 @@ def resolve_worker_rank() -> WorkerRank:
     """Read this process's rank from the env torchrun exports.
 
     Defaults to a single in-process rank when the module is launched bare, so a worker can
-    be run by hand (or in a test) without a torchrun agent.
+    be run by hand (or in a test) without a torchrun agent. A worker launched through
+    :mod:`slide2vec.distributed.pin_gpu` sees only its own GPU, which is then ``cuda:0``.
     """
+    local_rank = int(os.environ.get("LOCAL_RANK", "0"))
     return WorkerRank(
         global_rank=int(os.environ.get("RANK", "0")),
         world_size=int(os.environ.get("WORLD_SIZE", "1")),
-        local_rank=int(os.environ.get("LOCAL_RANK", "0")),
+        local_rank=local_rank,
+        device_ordinal=0 if os.environ.get(PINNED_ENV) == "1" else local_rank,
     )
 
 
@@ -82,6 +91,6 @@ def worker_progress_context(request: dict, *, rank: WorkerRank):
         return nullcontext()
     return activate_progress_reporter(
         JsonlProgressReporter(
-            progress_events_path, rank=rank.global_rank, progress_label=rank.device
+            progress_events_path, rank=rank.global_rank, progress_label=f"cuda:{rank.local_rank}"
         )
     )

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/runtime/dense_image_stage.py

@@ -275,6 +275,7 @@ def _run_dense_images_distributed(
         request_path.write_text(json.dumps(request, indent=2, sort_keys=True), encoding="utf-8")
         run_torchrun_worker(
             module="slide2vec.distributed.dense_image_worker",
+            pin_gpus=True,  # No collectives: each rank needs only its own GPU.
             num_gpus=execution.num_gpus,
             output_dir=out_dir,
             request_path=request_path,

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/runtime/dense_stage.py

@@ -297,6 +297,7 @@ def _run_dense_distributed(model, specs, *, dense, execution, out_dir) -> None:
         request_path.write_text(json.dumps(request, indent=2, sort_keys=True), encoding="utf-8")
         run_torchrun_worker(
             module="slide2vec.distributed.dense_worker",
+            pin_gpus=True,  # No collectives: each rank needs only its own GPU.
             num_gpus=execution.num_gpus,
             output_dir=out_dir,
             request_path=request_path,

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/runtime/distributed.py

@@ -158,18 +158,28 @@ def run_torchrun_worker(
     output_dir: Path,
     request_path: Path,
     failure_title: str,
+    pin_gpus: bool = False,
     progress_events_path: Path | None = None,
     progress_event_callback: Callable[[Any], None] | None = None,
     popen_factory=subprocess.Popen,
 ) -> None:
+    """Run ``module`` once per GPU under torchrun.
+
+    ``pin_gpus`` shows each rank only its own GPU (see :mod:`slide2vec.distributed.pin_gpu`).
+    Use it for workers that run no collectives.
+    """
+    if pin_gpus:
+        # By path, not ``-m``: the bootstrap must run before the slide2vec package is imported.
+        worker = [str(Path(__file__).resolve().parents[1] / "distributed" / "pin_gpu.py"), module]
+    else:
+        worker = ["-m", module]
     command = [
         sys.executable,
         "-m",
         "torch.distributed.run",
         "--standalone",
         f"--nproc_per_node={num_gpus}",
-        "-m",
-        module,
+        *worker,
         "--output-dir",
         str(output_dir),
         "--request-path",
@@ -188,9 +198,15 @@ def run_torchrun_worker(
             previous_sigterm = signal.signal(signal.SIGTERM, _raise_on_sigterm)
         except (ValueError, OSError):
             previous_sigterm = None
+    # Workers keep the parent's working directory, so a relative output_dir (and every path
+    # derived from it: the request, the tiling artifacts, the progress log) means the same
+    # place in both. PYTHONPATH, not cwd, is what lets an uninstalled checkout be imported.
+    package_root = str(Path(__file__).resolve().parents[2])
+    env = dict(os.environ)
+    env["PYTHONPATH"] = os.pathsep.join(filter(None, [package_root, env.get("PYTHONPATH")]))
     process = popen_factory(
         command,
-        cwd=str(Path(__file__).resolve().parents[2]),
+        env=env,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/runtime/distributed_stage.py

@@ -153,6 +153,7 @@ def run_distributed_embedding_stage(
         output_dir=output_dir,
         request_path=request_path,
         failure_title="Distributed feature extraction failed",
+        pin_gpus=True,
         progress_events_path=progress_events_path,
         progress_event_callback=on_progress_event,
         popen_factory=Popen,
@@ -190,6 +191,7 @@ def run_distributed_direct_embedding_stage(
         output_dir=output_dir,
         request_path=request_path,
         failure_title="Distributed direct embedding failed",
+        pin_gpus=True,
         progress_events_path=progress_events_path,
         popen_factory=Popen,
     )

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec/runtime/image_stage.py

@@ -147,6 +147,7 @@ def _run_images_distributed(model, specs, *, execution, out_dir) -> None:
         request_path.write_text(json.dumps(request, indent=2, sort_keys=True), encoding="utf-8")
         run_torchrun_worker(
             module="slide2vec.distributed.image_worker",
+            pin_gpus=True,  # No collectives: each rank needs only its own GPU.
             num_gpus=execution.num_gpus,
             output_dir=out_dir,
             request_path=request_path,

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.0.0
+Version: 6.1.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,7 @@ Requires-Dist: numpy<2; extra == "fm"
 Requires-Dist: pandas; extra == "fm"
 Requires-Dist: pillow; extra == "fm"
 Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec.egg-info/SOURCES.txt

@@ -3,9 +3,11 @@ README.md
 pyproject.toml
 slide2vec/__init__.py
 slide2vec/__main__.py
+slide2vec/_cufile.py
 slide2vec/api.py
 slide2vec/artifacts.py
 slide2vec/cli.py
+slide2vec/cufile.json
 slide2vec/inference.py
 slide2vec/progress.py
 slide2vec.egg-info/PKG-INFO
@@ -27,6 +29,7 @@ slide2vec/distributed/dense_image_worker.py
 slide2vec/distributed/dense_worker.py
 slide2vec/distributed/direct_embed_worker.py
 slide2vec/distributed/image_worker.py
+slide2vec/distributed/pin_gpu.py
 slide2vec/distributed/pipeline_worker.py
 slide2vec/distributed/worker_entry.py
 slide2vec/encoders/__init__.py
@@ -113,6 +116,7 @@ slide2vec/utils/utils.py
 tests/test_architecture_runtime_split.py
 tests/test_attention_extraction.py
 tests/test_benchmark_tooling.py
+tests/test_cufile_compat_mode.py
 tests/test_dense_encode_kit.py
 tests/test_dense_encoder_input.py
 tests/test_dense_extraction.py
@@ -135,6 +139,7 @@ tests/test_encoder_preprocessing.py
 tests/test_encoder_provider_failures.py
 tests/test_encoder_registry.py
 tests/test_gpfm_genbio_heavy.py
+tests/test_hs2p5_integration.py
 tests/test_hs2p_package_cutover.py
 tests/test_image_shard.py
 tests/test_image_stage.py
@@ -163,4 +168,5 @@ tests/test_slide_coordinate_preparation.py
 tests/test_soma_migration.py
 tests/test_tile_store.py
 tests/test_tiling_pipeline.py
-tests/test_titan.py
+tests/test_titan.py
+tests/test_worker_gpu_pinning.py

{slide2vec-6.0.0 → slide2vec-6.1.0}/slide2vec.egg-info/requires.txt

@@ -1,4 +1,4 @@
-hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 omegaconf
 matplotlib
 numpy<2
@@ -27,7 +27,7 @@ numpy<2
 pandas
 pillow
 rich
-hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 wandb
 torch<2.8,>=2.3
 torchvision>=0.18.0

slide2vec-6.1.0/tests/test_cufile_compat_mode.py

@@ -0,0 +1,50 @@
+"""``import cucim`` must not open a CUDA context on every visible GPU (issue #326).
+
+Without ``nvidia-fs``, cuFile's compat mode creates an idle context per device at import.
+slide2vec points cuFile at a config that disallows compat mode, before cucim can load.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import slide2vec
+from slide2vec import _cufile
+
+
+def test_packaged_config_disallows_compat_mode():
+    config = json.loads(Path(slide2vec.__file__).with_name("cufile.json").read_text())
+    assert config == {"properties": {"allow_compat_mode": False}}
+
+
+def test_cufile_is_pointed_at_the_packaged_config():
+    environ: dict[str, str] = {}
+    _cufile.disable_cufile_compat_mode(environ)
+    assert Path(environ[_cufile.CUFILE_ENV]) == Path(slide2vec.__file__).with_name("cufile.json")
+
+
+def test_a_config_the_user_chose_is_left_alone():
+    environ = {_cufile.CUFILE_ENV: "/etc/my-cufile.json"}
+    _cufile.disable_cufile_compat_mode(environ)
+    assert environ[_cufile.CUFILE_ENV] == "/etc/my-cufile.json"
+
+
+def test_package_import_sets_it_before_any_other_import():
+    # cuFile reads the variable once, when cucim is imported; nothing may get there first.
+    first, second = ast.parse(Path(slide2vec.__file__).read_text()).body[:2]
+    assert isinstance(first, ast.ImportFrom) and first.module == "slide2vec._cufile"
+    assert isinstance(second, ast.Expr) and second.value.func.id == "disable_cufile_compat_mode"
+
+
+def test_importing_slide2vec_exports_the_variable():
+    env = {k: v for k, v in os.environ.items() if k != _cufile.CUFILE_ENV}
+    out = subprocess.run(
+        [sys.executable, "-c", f"import os, slide2vec; print(os.environ['{_cufile.CUFILE_ENV}'])"],
+        env=env, capture_output=True, text=True, check=True, cwd=Path(slide2vec.__file__).parents[1],
+    ).stdout.strip().splitlines()[-1]
+    assert Path(out).name == "cufile.json" and Path(out).is_file()