macOS Apple Silicon: dbt-fabric fails with 'Library not loaded: libodbc.2.dylib' — missing setup guidance for pyodbc + unixODBC version mismatch

[anix-lynch]

Environment

• OS: macOS (Apple Silicon, M4 Pro)
• Python: 3.11 (venv)
• dbt-fabric: latest
• ODBC Driver: Microsoft ODBC Driver 18 for SQL Server (installed via brew install msodbcsql18)
• unixODBC: installed via Homebrew (brew install unixodbc)

Error

ImportError: dlopen(/path/to/.venv/lib/python3.11/site-packages/pyodbc.cpython-311-darwin.so, 0x0002): 
Library not loaded: /opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib
  Referenced from: pyodbc.cpython-311-darwin.so
  Reason: tried:
    '/opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib' (no such file)
    '/System/Volumes/Preboot/Cryptexes/OS/opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib' (no such file)

Steps to Reproduce

# 1. Create venv, install dbt-fabric
python3.11 -m venv .venv && source .venv/bin/activate
pip install dbt-fabric

# 2. Install ODBC deps via Homebrew
brew install unixodbc msodbcsql18

# 3. Run dbt debug
dbt debug --profiles-dir .
# → ImportError: Library not loaded: libodbc.2.dylib

Root Cause

pyodbc is compiled against libodbc.2.dylib. Homebrew on newer macOS versions (especially post-Sonoma on Apple Silicon) ships libodbc.3.dylib instead. The binary dependency path is baked into the compiled .so and doesn't fall back gracefully.

Specifically, when pip install pyodbc builds from source (or pulls a wheel compiled on an older Homebrew), it links against libodbc.2. But Homebrew's current unixODBC ships libodbc.3.

Verification:

ls /opt/homebrew/opt/unixodbc/lib/
# libodbc.3.dylib  ← exists
# libodbc.2.dylib  ← MISSING (this is what pyodbc expects)

Workaround (took 2+ hours to discover)

# Reinstall pyodbc after ensuring unixodbc is on PATH
export LDFLAGS="-L/opt/homebrew/opt/unixodbc/lib"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include"
pip install --force-reinstall --no-binary :all: pyodbc

OR create a symlink:

ln -s /opt/homebrew/opt/unixodbc/lib/libodbc.3.dylib /opt/homebrew/opt/unixodbc/lib/libodbc.2.dylib

Ask

1. Add macOS setup section to README/docs — specifically calling out the LDFLAGS/CPPFLAGS env vars required when installing in a venv on Apple Silicon
2. Consider pinning or documenting tested pyodbc wheel versions for macOS targets
3. Better error output — the current dbt error log swallows the ImportError; surface it more clearly in dbt debug output so users don't spend hours debugging a dylib path issue

This is a blocking install failure on Apple Silicon Macs. The current docs only say 'install unixODBC' which is insufficient — the version compatibility between pyodbc's compiled binary and Homebrew's libodbc is the real issue.

---

Encountered while building a healthcare analytics dbt-fabric project on Mac M4 Pro. Workaround verified.

[pradeepsrikakolapu]

Updating the docs in #368 release