在C++项目中调用CPython的Py_Initialize报错：找不到'encodings'模块

当在C++中嵌入CPython并使用虚拟环境（venv）时，Py_Initialize()默认会尝试使用系统Python的路径，导致无法找到虚拟环境内的核心encodings模块，从而触发你遇到的错误。以下是具体解决步骤：

1. 手动指定虚拟环境路径 #

在调用Py_Initialize()之前，必须通过Py_SetPythonHome()API告知CPython虚拟环境的根目录位置。修改你的初始化代码如下：

#include <Python.h>
#include <stdexcept>
#include <string>

class PyRuntime {
public:
    PyRuntime(const std::string& venv_root) {
        // 设置虚拟环境为Python运行时的Home目录
        Py_SetPythonHome(venv_root.c_str());

        // 初始化Python运行时
        Py_Initialize();
        if (PyErr_Occurred()) {
            throw std::runtime_error("Py_Initialize failed");
        }
    }

    ~PyRuntime() {
        if (Py_IsInitialized()) {
            Py_FinalizeEx(); // 更安全的终止API，替代Py_Finalize()
        }
    }
};

int main(int argc, char** argv) {
    // 替换为你的虚拟环境实际路径（相对/绝对路径均可）
    const std::string venv_path = "./venv";
    try {
        PyRuntime rt(venv_path);
    } catch (const std::runtime_error& e) {
        fprintf(stderr, "Error: %s\n", e.what());
        return 1;
    }
    return 0;
}

2. 编译时链接虚拟环境的Python库 #

编译C++代码时，必须指定虚拟环境内的Python头文件和库文件路径，避免链接到系统Python。以Linux为例，编译命令模板如下（替换为你的Python版本和路径）：

g++ your_code.cpp -o py_embed \
  -I./venv/include/python3.10 \
  -L./venv/lib/python3.10/config-3.10-x86_64-linux-gnu \
  -L./venv/lib \
  -lpython3.10 \
  -Wl,-rpath=./venv/lib

• -I：指定虚拟环境下的Python头文件目录
• -L：指定虚拟环境下的Python库文件目录
• -Wl,-rpath：让程序运行时自动加载虚拟环境内的动态链接库（避免手动设置LD_LIBRARY_PATH）

3. 可选：手动补充sys.path（如果仍有模块找不到） #

如果设置PythonHome后仍存在模块查找问题，可以手动向sys.path添加虚拟环境的site-packages路径：
在Py_Initialize()之后添加以下代码：

// 获取sys模块
PyObject* sys_module = PyImport_ImportModule("sys");
// 获取sys.path列表
PyObject* sys_path = PyObject_GetAttrString(sys_module, "path");
// 向path添加虚拟环境的site-packages路径（替换为实际路径）
PyList_Append(sys_path, PyUnicode_FromString("./venv/lib/python3.10/site-packages"));

// 释放引用，避免内存泄漏
Py_DECREF(sys_path);
Py_DECREF(sys_module);

关键说明 #

• Py_SetPythonHome()是核心：它让CPython明确知道去哪里寻找标准库（包括encodings模块）和虚拟环境的依赖
• 避免混用环境：编译、运行时必须全程使用虚拟环境内的Python资源，不能和系统Python交叉使用
• 优先使用Py_FinalizeEx()：相比Py_Finalize()，它会返回终止状态，是更现代、安全的终止API

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