群晖NAS上使用pyodbc连接MS SQL时遇文件未找到错误

问题核心 #

本地Mac上可正常执行的代码：通过requests.get获取HTTP数据转成DataFrame，再用pyodbc插入群晖NAS上的MS SQL Server，但在群晖上运行时触发错误：

pyodbc.Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib '/usr/local/lib/libmsodbcsql.18.dylib' : file not found (0) (SQLDriverConnect)")

已完成排查 #

• 通过SSH连接群晖，尝试用Homebrew安装微软官方驱动，安装后仍报错无法打开驱动文件
• 验证驱动路径、创建软链接、手动复制dylib文件到odbcinst.ini指定路径，无效
• 更换MySQL驱动可成功连接，排除pyodbc本身及ODBC管理器的问题
• 重装Homebrew、MSSQL驱动、pyodbc、Python，问题依旧

解决方案 #

关键前提：群晖是Linux内核系统，不能使用macOS的.dylib驱动 #

群晖底层为Linux，而libmsodbcsql.18.dylib是macOS专属的动态库格式，必须安装Linux版MS ODBC驱动（.so格式），步骤如下：

1. 卸载原有macOS版驱动
   若之前通过Homebrew安装了macOS版驱动，先卸载：

   brew uninstall msodbcsql18 mssql-tools18
   

2. 安装Linux版微软ODBC驱动
   先通过uname -m确认群晖CPU架构（x86_64/arm64），再对应安装：

   • Debian/Ubuntu系群晖（多数机型适用）：

     # 导入微软密钥
     curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -
     # 添加微软源（根据群晖Debian版本调整，如10/11）
     curl https://packages.microsoft.com/config/debian/11/prod.list > /etc/apt/sources.list.d/mssql-release.list
     # 更新源并安装驱动
     apt-get update
     ACCEPT_EULA=Y apt-get install -y msodbcsql18 mssql-tools18
     

   • RPM系群晖（少数机型）：

     # 导入微软密钥
     rpm --import https://packages.microsoft.com/keys/microsoft.asc
     # 添加微软源
     curl https://packages.microsoft.com/config/rhel/8/prod.repo > /etc/yum.repos.d/mssql-release.repo
     # 安装驱动
     ACCEPT_EULA=Y yum install -y msodbcsql18 mssql-tools18
     

3. 配置odbcinst.ini
   找到odbcinst.ini的位置（通常为/etc/odbcinst.ini或~/.odbcinst.ini），修改为以下内容（驱动路径需匹配实际安装位置）：

   [ODBC Driver 18 for SQL Server]
   Description=Microsoft ODBC Driver 18 for SQL Server
   Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.3.so.2.1
   UsageCount=1
   

   可通过find /opt -name "libmsodbcsql-*.so"命令查找准确的驱动文件路径。

4. 验证驱动与连接

   • 查看ODBC管理器信息：odbcinst -j
   • 测试SQL Server连接（替换占位符）：

     isql -v "DRIVER={ODBC Driver 18 for SQL Server};SERVER=<你的SQL服务器地址>;UID=<用户名>;PWD=<密码>"
     

5. 调整代码中的连接字符串
   确保连接字符串里的驱动名称为ODBC Driver 18 for SQL Server，不再指向.dylib文件，示例：

   conn_str = (
       "DRIVER={ODBC Driver 18 for SQL Server};"
       "SERVER=你的服务器地址;"
       "DATABASE=你的数据库名;"
       "UID=用户名;"
       "PWD=密码;"
       "TrustServerCertificate=yes"
   )
   

额外注意 #

• 确保运行Python的用户对驱动文件（/opt/microsoft/msodbcsql18/下的文件）有读取权限
• 若群晖启用了权限管控，需确认SSH用户有足够的系统操作权限（如sudo）

内容的提问来源于stack exchange，提问作者Bobby Franklin