pylibfreenect2安装后无法导入Freenect2问题求助

问题背景 #

按步骤安装pylibfreenect2时，执行python setup.py install出现编译错误，提示找不到libfreenect2.pxd文件，同时伴随Cython相关警告与弃用提示。为解决编译问题，将setup.py移至pylibfreenect2文件夹内，并修改了Extension的sources路径（移除了原路径中的pylibfreenect2/前缀），编译安装成功后，运行from pylibfreenect2 import Freenect2时出现ImportError: cannot import name 'Freenect2' from 'pylibfreenect2' (unknown location)错误。已确认libfreenect2-0.2.0-usbdk-vs2015-x64配置正常，Protonect.exe可正常显示Kinect设备图像。

问题原因 #

修改setup.py的位置和路径后，虽然解决了编译时的文件查找问题，但破坏了Python包的标准结构：

• 将setup.py移至子文件夹后，安装过程生成的包结构不符合pylibfreenect2的预期，导致Python解释器无法定位Freenect2所在的模块
• 修改sources路径后，编译生成的扩展模块命名空间出现异常，无法被主模块正确导出

解决方案 #

方案1：恢复原目录结构，修正编译路径（推荐） #

不要移动setup.py，通过调整setup.py的配置解决编译时找不到.pxd文件的问题：

1. 确保setup.py位于项目根目录（与pylibfreenect2文件夹同级）
2. 修改setup.py中的Extension配置，添加include_dirs参数指定.pxd文件所在的路径：

ext_modules = cythonize(
    [Extension(
        name="pylibfreenect2.libfreenect2",
        sources=[
            join("pylibfreenect2", "libfreenect2" + ext),
        ],
        include_dirs=[
            "pylibfreenect2",  # 让Cython能找到libfreenect2.pxd文件
            # 保留原有的libfreenect2头文件路径，比如你的libfreenect2安装路径下的include目录
        ],
        # 其他编译参数（library_dirs、libraries等）保持不变
    )]
)

3. 重新执行python setup.py install完成安装

方案2：修复移动setup.py后的包结构 #

如果需要保留setup.py在pylibfreenect2文件夹内，需调整包的导出配置：

1. 打开pylibfreenect2/__init__.py，确保明确导入并导出Freenect2类：

# pylibfreenect2/__init__.py
from .libfreenect2 import Freenect2
# 若需要使用其他类/函数，可在此一并添加导出，比如：
# from .libfreenect2 import SyncMultiFrameListener, FrameType

2. 重新执行python setup.py install，安装完成后检查Python的site-packages/pylibfreenect2目录，确认libfreenect2.pyd（Windows）或libfreenect2.so（Linux）存在，且__init__.py配置正确

额外检查项 #

• 确认pylibfreenect2版本与libfreenect2-0.2.0兼容，尽量使用对应版本的pylibfreenect2源码
• Windows下建议以管理员权限执行安装命令，避免权限问题导致文件未正确写入site-packages
• 可使用pip install -e .（开发模式）替代setup.py install，方便调试包结构问题

内容的提问来源于stack exchange，提问作者Sergey Lukin