segmentation fault in normalize_total (Numba omp) on Apple Silicon

[JiayuSuPKU]

Please make sure these conditions are met

• I have checked that this issue has not already been reported.
• I have confirmed this bug exists on the latest version of scanpy.
• (optional) I have confirmed this bug exists on the main branch of scanpy.

What happened?

Probably related to #3507. Posting it again since I could not find an existing solution. The workaround is to manually set NUMBA_THREADING_LAYER=workqueue.

Problem: When scanpy and torch are both loaded, sc.pp.normalize_total can crash (segmentation fault) with warning

 OMP: Info #276: omp_set_nested routine deprecated, please use omp_set_max_active_levels instead.

import scanpy as sc
import torch
from scipy.sparse import csr_matrix
X = csr_matrix(torch.eye(100).numpy())
ad = sc.AnnData(X=X)
sc.pp.normalize_total(ad, target_sum=1e4)

Densifying ad.X first before running sc.pp.normalize_total can rescue the crash. Also, importing numpy only will throw the same OMP message but does not lead to segfault crash.

Root cause: Numba's @njit with numba.prange (parallel execution) in _normalize_csr. Numba's default threading layer on macOS/M-chip is omp (LLVM OpenMP). On Apple Silicon, Numba 0.64.0 with OpenMP threading throws the OMP warning (omp_set_nested deprecated). When torch is also imported, this somehow leads to crashes with a segfault.

A potential issue may be libomp.dylib. sklearn bundles libomp.dylib with install name /DLC/sklearn/.dylibs/libomp.dylib, while torch ships its own libomp.dylib with install name /opt/llvm-openmp/lib/libomp.dylib. Both may get loaded as separate OMP runtimes, and the LLVM OMP runtime crashes on detecting a duplicate.

Potential fix: Set NUMBA_THREADING_LAYER=workqueue which uses Numba's own platform-agnostic thread pool (no OpenMP dependency)

export NUMBA_THREADING_LAYER=workqueue

Or alternatively,

import os; os.environ['NUMBA_THREADING_LAYER'] = 'workqueue'
import scanpy as sc
import torch

Minimal code sample

conda create -n scanpy_test python=3.12 r-base
conda activate scanpy_test
pip install scanpy==1.12 torch==2.11

The r-base installation somehow is required to replicate the behavior.

import scanpy as sc
import torch
from scipy.sparse import csr_matrix
X = csr_matrix(torch.eye(100).numpy())
ad = sc.AnnData(X=X)
sc.pp.normalize_total(ad, target_sum=1e4)

Error output

OMP: Info #276: omp_set_nested routine deprecated, please use omp_set_max_active_levels instead.
[1]    72347 segmentation fault  python

Versions

Details

scanpy	1.12
----	----
packaging	26.0
donfig	0.8.1.post1
typing_extensions	4.15.0
joblib	1.5.3
anndata	0.12.10
kiwisolver	1.5.0
h5py	3.16.0
numpy	2.4.4
PyYAML	6.0.3
session-info2	0.4
natsort	8.4.0
cycler	0.12.1
legacy-api-wrap	1.5
six	1.17.0
threadpoolctl	3.6.0
fast-array-utils	1.4
scipy	1.17.1
python-dateutil	2.9.0.post0
pillow	12.1.1
numba	0.64.0
numcodecs	0.16.5
scikit-learn	1.8.0
setuptools	81.0.0
fsspec	2026.3.0
llvmlite	0.46.0
pandas	2.3.3
matplotlib	3.10.8
google-crc32c	1.8.0
pyparsing	3.3.2
pytz	2026.1.post1
zarr	3.1.6
----	----
Python	3.12.13 | packaged by conda-forge | (main, Mar  5 2026, 17:06:14) [Clang 19.1.7 ]
OS	macOS-26.4-arm64-arm-64bit
CPU	8 logical CPU cores, arm
GPU	No GPU found
Updated	2026-04-01 02:04

[flying-sheep]

Oh wow, I didn’t know about the “two libOMPs” situation, but that might explain #3507. So numba will detect when (at least) one of them is loaded and activate its OMP backend?

PS: using workqueue is going to work even with numba-in-dask soon because of #4015

[JiwaniZakir]

The crash stems from multiple conflicting OpenMP runtimes being loaded simultaneously — scikit-learn bundles its own libomp.dylib and PyTorch ships another, and when Numba's @njit/prange in _normalize_csr initializes LLVM OpenMP as its threading layer, the duplicate runtime detection triggers a segfault. The OMP: Info #276 warning about omp_set_nested being deprecated is a tell-tale sign that the LLVM OpenMP runtime is initializing, which is what ultimately collides with the already-loaded torch OpenMP runtime. Setting NUMBA_THREADING_LAYER=workqueue sidesteps this entirely by bypassing OpenMP in favor of Numba's own thread pool, and it may be worth hardcoding this as a default in scanpy's _normalize_csr via numba.config.THREADING_LAYER = 'workqueue' or by decorating with @njit(parallel=True) alongside a config guard, so users don't have to set the env var manually. The fact that densifying ad.X first avoids the crash makes sense — the dense path presumably doesn't invoke the parallel Numba kernel.

[JiayuSuPKU]

Oh wow, I didn’t know about the “two libOMPs” situation, but that might explain #3507. So numba will detect when (at least) one of them is loaded and activate its OMP backend?

Seems to have an LLM-generated comment above :)

Claude Code's diagnosis may be more helpful

Root Cause Analysis

macOS's dyld is loading three distinct copies of libomp.dylib, treating them as separate libraries due to different install names:

1. Numba: Loads $ENV/lib/libomp.dylib via Python's RPATH.
2. PyTorch: Loads its bundled /opt/llvm-openmp/lib/libomp.dylib at import.
3. Scikit-Learn: Loads its bundled /DLC/sklearn/.dylibs/libomp.dylib at import.

When Numba initializes its OMP threading layer, it detects Torch/Sklearn's already-initialized OMP runtimes and calls abort().

Why does this only happen with r-base installed?

Installing r-base pulls in llvm-openmp (via gfortran), which places libomp.dylib in the conda environment's lib/ folder. Without r-base, this file doesn't exist, causing Numba to silently fall back to the workqueue threading layer—avoiding the OpenMP conflict entirely.

Why does this only happen with sparse data?

Scanpy's @njit wrapper (scanpy/_compat.py) only dispatches to parallel=True for CSRBase matrices. Dense arrays use a different code path that doesn't trigger Numba's omppool initialization.

---

Workarounds & Fixes

For Users (Immediate Fix):
Force Numba to use the workqueue threading layer instead of OpenMP.

import os
os.environ['NUMBA_THREADING_LAYER'] = 'workqueue'
import scanpy as sc

(Note: Setting KMP_DUPLICATE_LIB_OK=TRUE also prevents the crash but is unsafe and may cause incorrect results).

For Maintainers (Potential Upstream Fixes):

1. Scanpy: Gate the parallel=True dispatch on the Numba threading layer, or add a runtime check to auto-select workqueue (or warn the user) when conflicting OMP runtimes are detected.
2. Packaging (Long-term): PyTorch, Scikit-Learn, and conda-forge ideally need to coordinate on a single shared libomp rather than bundling their own conflicting versions.

</p>
</details> 

[flying-sheep]

Both of you, please put LLM output in quotes or “details” tags instead of having them be part of your response.

This makes it easier to distinguish things you verified vs speculation. E.g. did you verify that llvm-openmp causes the problem, not r-base? Or is that speculation? Telling me is more respectful of my time.

Quoting myself from #4027:

I think we could approach this in two ways at the same time: a workaround and a real fix.

1. the workaround in fast-array-utils’ njit could be amended to also detect the broken OMP runtime (next to what it already does) and dispatch to the single threaded version, that would mean a PR in that package
2. the real fix would be to make sure no two libomps are loaded into the same process somehow. sklearn and pytorch seem to be aware of the problem and able to work around it, but llvm-openmp combined with one of them might be the problem. So maybe we can make numba detect a loaded libomp and avoid loading another one.

[stuartarchibald]

Numba doesn't try and "detect" anything for OpenMP, it simply tries to load its OpenMP backed threading layer, which has declared linkage against an OpenMP library, and if it manages to load it OK then it is assumed that everything is well. It is the result of the load via the dynamic-linker that is providing the "detection" in the above.

If something is putting an OpenMP library into the process or the library search path in such a way that when Numba does "try and load the OpenMP backend" it manages to find it, then Numba will try and use it. If there is more than one OpenMP library in the process, depending on how they are loaded by the dynamic linker, and whether they are ABI compatible, you may or may not get issues (like segmentation faults). The warning RE omp_set_nested might not be related to the segmentation fault at all, or it might be the cause of it if there are symbol interposition/ABI/resource issues, would need to run under a debugger to find out.

[flying-sheep]

@stuartarchibald how can @JiayuSuPKU figure out which library numba actually tries to load and why?

[stuartarchibald]

Numba provides a command line tool numba -s to show how it is configured and what is working/not working. Maybe try with that first and see if it helps with identifying which backends are available.

[JiayuSuPKU]

@stuartarchibald @flying-sheep Thank you for looking into this.

The warning RE omp_set_nested might not be related to the segmentation fault at all, or it might be the cause of it if there are symbol interposition/ABI/resource issues, would need to run under a debugger to find out.

Yes the warning itself does not cause segfault. As mentioned in the OP, replacing torch with numpy will throw the same OMP message but does not crash. I have since ran more experiments to locate the root cause. Below is my current understanding:

1. Three separate libomp.dylib copies (conda/llvm-openmp, torch-bundled, sklearn-bundled) are loaded into one process with different install names.
2. The LLVM OMP runtime exports C++ template specializations like __kmp_suspend_64<false,true> as weak symbols. macOS coalesces weak symbols across dylibs (even under two-level namespace) so all calls route to the first-loaded copy (torch's).
3. When conda's libomp (used by numba) calls the coalesced function, it executes inside torch's libomp, which looks up threads in torch's internal __kmp_threads[] array using a GTID assigned by conda's instance. The lookup returns NULL. Dereference of NULL + 0x580 → segfault.

The extra conda copy llvm-openmp, pulled in via gfortran when installing r-base, placing libomp.dylib in $ENV/lib/. Without it, numba's omppool.so can't resolve its @rpath/libomp.dylib dependency (the baked RPATH is a non-existent CI path), so numba silently falls back to workqueue (no OMP, no conflict).

Here is a full report compiled by Claude Code with reproducible experiments

Numba + Torch Segfault on macOS/ARM64: Root Cause Analysis

Environment: macOS 26.4 / Apple M4 / conda-forge
Packages: scanpy 1.12, torch 2.11, numba 0.65.0, scikit-learn 1.8.0, r-base 4.5.3
Reproduction env: conda create -n scanpy_test python=3.12 r-base && pip install scanpy==1.12 torch==2.11

---

1. The crash

import scanpy as sc; import torch
from scipy.sparse import csr_matrix; import numpy as np
sc.pp.normalize_total(sc.AnnData(X=csr_matrix(np.eye(100))), target_sum=1e4)
# => OMP: Info #276: omp_set_nested routine deprecated ...
# => [1] segmentation fault  (exit 139)

2. Root cause summary

Three independent copies of LLVM's libomp.dylib are loaded into one process.
Numba's OMP threading backend (loaded last) shares weak C++ template symbols
with torch's libomp (loaded earlier). macOS coalesces these weak symbols to the
first-loaded instance. The coalesced function accesses torch's internal thread
registry, but the calling thread was registered by numba/conda's instance —
the lookup returns NULL, and the process segfaults dereferencing NULL + 0x580.

3. Evidence

3.1 Three distinct libomp.dylib copies exist

$ otool -D $ENV/lib/libomp.dylib
  @rpath/libomp.dylib                          # conda (from llvm-openmp, via r-base)

$ otool -D $ENV/.../torch/lib/libomp.dylib
  /opt/llvm-openmp/lib/libomp.dylib            # torch-bundled

$ otool -D $ENV/.../sklearn/.dylibs/libomp.dylib
  /DLC/sklearn/.dylibs/libomp.dylib            # sklearn-bundled

All have different install names → macOS loads them as separate images.

3.2 All four images load into one process

Verified with DYLD_PRINT_LIBRARIES=1:

#1  sklearn/.dylibs/libomp.dylib   (UUID: E3A31AB3)
#2  torch/lib/libomp.dylib         (UUID: E56FEBF1)
#3  numba/.../omppool.cpython-312-darwin.so  (UUID: EA9BF43B)
#4  $ENV/lib/libomp.dylib          (UUID: 6C44EF24)   ← dependency of #3

3.3 __kmp_suspend_64 is a weak symbol — subject to coalescing

$ nm -m $ENV/lib/libomp.dylib | grep 'weak.*kmp_suspend_64.*Lb0.*Lb1'
  weak external __Z16__kmp_suspend_64ILb0ELb1EEviP11kmp_flag_64IXT_EXT0_EE

$ nm -m $ENV/.../torch/lib/libomp.dylib | grep 'weak.*kmp_suspend_64.*Lb0.*Lb1'
  weak external __Z16__kmp_suspend_64ILb0ELb1EEviP11kmp_flag_64IXT_EXT0_EE

On macOS, weak symbols are coalesced even under two-level namespace (confirmed by
the WEAK_DEFINES + BINDS_TO_WEAK Mach-O header flags on both libraries).
The first-loaded definition (#2, torch) wins for all callers including #4 (conda).

3.4 The crash backtrace proves the cross-library call

From lldb (with KMP_DUPLICATE_LIB_OK=TRUE to suppress the abort and reach the segfault):

thread #2, stop reason = EXC_BAD_ACCESS (code=1, address=0x580)

frame #0: 0x10bfff66c libomp.dylib __kmp_suspend_initialize_thread + 32
frame #1: 0x10c000114 libomp.dylib __kmp_suspend_64<false, true> + 68
frame #2: 0x117087a80 libomp.dylib kmp_flag_64<false, true>::wait + 1896
frame #3: 0x117082df4 libomp.dylib __kmp_hyper_barrier_release + 172
frame #4: 0x1170865c8 libomp.dylib __kmp_fork_barrier + 464
frame #5: 0x11705eaa4 libomp.dylib __kmp_launch_thread + 336
frame #6: 0x1170a6c38 libomp.dylib __kmp_launch_worker + 280

Image list from the same run:

[0] E3A31AB3 0x10b6ac000  sklearn/.dylibs/libomp.dylib
[1] E56FEBF1 0x10bf90000  torch/lib/libomp.dylib        ← frames 0-1
[2] 6C44EF24 0x117038000  $ENV/lib/libomp.dylib         ← frames 2-6

Verification:

Frame	Address	Library	Proof
0	0x10bfff66c	torch (base 0x10bf90000)	0x10bf90000 + 0x6f64c + 32 = 0x10bfff66c ✓
2	0x117087a80	conda (base 0x117038000)	0x117038000 + 0x4f318 + 1896 = 0x117087a80 ✓

Execution jumps from conda's kmp_flag_64::wait (frame 2) into torch's
__kmp_suspend_64 (frame 1) via the coalesced weak symbol. Torch's
implementation looks up the thread in its own __kmp_threads[] array
using a GTID assigned by conda's instance → returns NULL →
ldr w8, [NULL, #0x580] → EXC_BAD_ACCESS.

3.5 The crash is isolated to torch + numba-OMP (not scanpy-specific)

# Crashes (exit 134 = SIGABRT from OMP duplicate detection):
import torch
from numba import njit, prange
@njit(parallel=True)
def f(n):
    s = 0.0
    for i in prange(n): s += i
    return s
f(10)

No scanpy needed. The crash is between torch's libomp and conda/numba's libomp.

3.6 The omp_set_nested warning is unrelated to the crash

The warning fires whenever numba's OMP backend initializes — with or without torch:

# Without torch (no crash):
OMP: Info #276: omp_set_nested routine deprecated ...
OK

# With torch (crash):
OMP: Info #276: omp_set_nested routine deprecated ...
[1] segmentation fault

It is a benign OpenMP 5.1 deprecation message from omp_set_nested(0) called during
the OMP runtime's initialization. It appears before the crash only because both
happen during the first parallel region.

4. Why r-base is required

Without r-base, $ENV/lib/libomp.dylib does not exist:

r-base → gfortran_osx-arm64 → llvm-openmp → $ENV/lib/libomp.dylib

Numba's omppool.so links to @rpath/libomp.dylib. Its baked RPATH
(/Users/runner/miniconda3/envs/test/lib) is a conda-forge CI artifact that does
not exist on user machines. The @rpath is then resolved via Python's own RPATH
(@loader_path/../lib/ → $ENV/lib/). Without the file there, dlopen fails,
and numba silently falls back to the workqueue threading layer — no OMP, no conflict.

$ otool -l omppool.cpython-312-darwin.so | grep -A2 LC_RPATH
  path /Users/runner/miniconda3/envs/test/lib   ← does not exist on user machine

$ otool -l $ENV/bin/python | grep -A2 LC_RPATH
  path @loader_path/../lib/                     ← resolves to $ENV/lib/

Additionally, libgomp.dylib and libgomp.1.dylib are symlinks to libomp.dylib
(conda-forge maps GCC's libgomp to LLVM's libomp on macOS/ARM64).

5. Why dense matrices don't crash

Scanpy's @njit wrapper (scanpy/_compat.py:145) dispatches to parallel=True
only for CSR matrices. Dense arrays use a non-parallel path → numba never loads
omppool.so → no second OMP runtime → no conflict.

6. Fixes

Immediate workaround

export NUMBA_THREADING_LAYER=workqueue

This makes numba use its own platform-agnostic thread pool instead of OMP. Verified:

NUMBA_THREADING_LAYER=workqueue python -c "
import scanpy as sc; import torch
from scipy.sparse import csr_matrix; import numpy as np
sc.pp.normalize_total(sc.AnnData(X=csr_matrix(np.eye(100))), target_sum=1e4)
print('OK')
"
# => OK  (exit 0)

Alternative: install TBB

pip install tbb

Numba prefers TBB over OMP when available (selection order: tbb → omp → workqueue).
TBB does not conflict with libomp.

Upstream fixes needed

1. torch/sklearn: Use a shared libomp instead of bundling separate copies.
2. numba (pip wheel): The baked RPATH /Users/runner/miniconda3/envs/test/lib
   is a build artifact that should be stripped or replaced with @loader_path.
   Its accidental resolution via Python's RPATH is the proximate cause.
3. scanpy: Could detect multiple OMP runtimes at startup and auto-select
   workqueue, or set KMP_DUPLICATE_LIB_OK=TRUE with a warning.

Unsafe workaround (not recommended)

export KMP_DUPLICATE_LIB_OK=TRUE

Suppresses the abort() but allows the coalesced-symbol segfault to occur.