本文旨在解决 kivy 在 python 3.12 环境下安装失败的问题。核心原因是 kivy 及其依赖库尚未完全支持 python 3.12。教程将指导用户如何通过降级 python 版本、使用虚拟环境以及验证兼容性来成功安装 kivy，确保开发环境的稳定与高效。
Kivy 安装失败问题概述
在使用 pip install kivy 命令尝试安装 Kivy 框架时，部分用户可能会遇到 subprocess-exited-with-error 错误，尤其是在 Python 3.12 环境下。这个错误通常伴随着依赖项无法找到的提示，例如 ERROR: Could not find a version that satisfies the requirement kivy_deps.sdl2_dev~=0.6.0。
以下是典型的错误输出示例：
PS C:\Users\med\source\repos\PythonApplication2> python -m pip install kivy Collecting kivy Using cached Kivy-2.2.1.tar.gz (24.0 MB) Installing build dependencies ... error error: subprocess-exited-with-error pip subprocess to install build dependencies did not run successfully. exit code: 1 [12 lines of output] Collecting setuptools ... Collecting kivy_deps.gstreamer_dev~=0.3.3 ... ERROR: Could not find a version that satisfies the requirement kivy_deps.sdl2_dev~=0.6.0 (from versions: 0.7.0) ERROR: No matching distribution found for kivy_deps.sdl2_dev~=0.6.0 [end of output] note: This error originates from a subprocess, and is likely not a problem with pip. error: subprocess-exited-with-error x pip subprocess to install build dependencies did not run successfully. exit code: 1 See above for output. note: This error originates from a subprocess, and is likely not a problem with pip.
此错误表明在尝试安装 Kivy 的构建依赖时，一个子进程未能成功执行。具体来说，它无法找到 kivy_deps.sdl2_dev 的兼容版本，这通常是由于 Python 版本不兼容导致的。
根本原因分析：Python 版本兼容性
根据 Kivy 社区的反馈，Kivy 及其核心依赖库在撰写本文时，尚未完全支持 Python 3.12 版本。这意味着即使您的 pip 版本是最新的，并且网络连接正常，尝试在 Python 3.12 环境下安装 Kivy 仍然会失败，因为 Kivy 的某些底层依赖（如 kivy_deps.sdl2_dev 等）还没有为 Python 3.12 提供预编译的轮子文件（wheels）或兼容的构建脚本。
立即学习“Python免费学习笔记（深入）”；
解决方案：使用兼容的 Python 版本与虚拟环境
解决此问题的最有效方法是使用 Kivy 已知支持的 Python 版本，并结合虚拟环境进行管理。
1. 确定兼容的 Python 版本
目前，Kivy 稳定支持的 Python 版本通常是 Python 3.11 或更早的版本（如 3.10、3.9）。在开始安装之前，请务必查阅 Kivy 官方文档或其 PyPI 页面，以获取最新的兼容性信息。
您可以通过以下命令检查当前系统或环境中正在使用的 Python 版本：
python --version
或
python3 --version
如果输出显示为 Python 3.12.x，则需要切换到或安装一个兼容的版本。
2. 安装兼容的 Python 版本
如果您当前系统只安装了 Python 3.12，您需要安装一个兼容的 Python 版本。
从 Python 官方网站下载： 访问 python.org，下载并安装 Python 3.11.x 或您选择的其他兼容版本。
-
使用版本管理工具： 对于需要管理多个 Python 版本的开发者，推荐使用 pyenv (Linux/macOS) 或 pyenv-win (Windows)。这些工具可以方便地安装和切换不同版本的 Python。
-
示例 (使用 pyenv):
# 安装 Python 3.11.x pyenv install 3.11.8 # 设置全局或局部 Python 版本 # pyenv global 3.11.8 # 设置为全局默认 # pyenv local 3.11.8 # 仅针对当前目录
-
示例 (使用 pyenv):
3. 创建并激活虚拟环境
强烈建议为每个项目使用独立的 Python 虚拟环境。这可以避免不同项目之间的依赖冲突，并允许您为特定项目指定特定的 Python 版本。
以下是使用 Python 内置的 venv 模块创建和激活虚拟环境的步骤：
打开命令行或终端。
导航到您的项目目录。
-
使用兼容的 Python 版本创建虚拟环境：
假设您已经安装了 Python 3.11，并且它可以通过 python3.11 命令访问（或者您已通过 pyenv 等工具切换到 3.11）。
# 使用 Python 3.11 创建名为 'kivy_env' 的虚拟环境 python3.11 -m venv kivy_env
如果您的系统默认 python 命令指向 Python 3.11，则可以直接使用：
python -m venv kivy_env
-
激活虚拟环境：
-
Windows:
.\kivy_env\Scripts\activate
-
macOS / Linux:
source kivy_env/bin/activate
激活成功后，您的命令行提示符前会显示虚拟环境的名称（例如 (kivy_env)）。
-
Windows:
4. 在虚拟环境中安装 Kivy
虚拟环境激活后，您现在可以使用 pip 命令在其中安装 Kivy。此时，pip 将会使用虚拟环境关联的 Python 版本及其依赖。
pip install kivy
如果需要安装特定的 Kivy 版本，或者包含额外依赖（如 kivy[full]），可以这样：
pip install "kivy==2.2.1" # 安装指定版本 pip install "kivy[full]" # 安装完整版，包含所有推荐依赖
安装过程应该会顺利进行，不再出现 Python 3.12 相关的依赖错误。
5. 验证 Kivy 安装
安装完成后，您可以运行一个简单的 Kivy 应用来验证安装是否成功。
-
在您的项目目录中创建一个名为 main.py 的文件：
# main.py from kivy.app import App from kivy.uix.label import Label class MyApp(App): def build(self): return Label(text='Hello, Kivy!') if __name__ == '__main__': MyApp().run() -
确保虚拟环境已激活，然后在命令行中运行：
python main.py
如果一切正常，应该会弹出一个显示 "Hello, Kivy!" 的窗口。
注意事项
- 持续关注官方更新： Kivy 团队正在积极开发和维护，未来一定会支持 Python 3.12 甚至更高版本。请定期查看 Kivy 的官方网站、GitHub 仓库或发布说明，以获取最新的兼容性信息。
-
IDE 配置： 在 Visual Studio Code 或 PyCharm 等 IDE 中，确保您的项目解释器已设置为您创建的虚拟环境中的 Python 版本，而不是系统默认的 Python 3.12。
- PyCharm: File -> Settings (或 PyCharm -> Preferences on macOS) -> Project: [Your Project Name] -> Python Interpreter。点击齿轮图标添加新的解释器，选择虚拟环境的路径。
- VS Code: 打开命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)，搜索 Python: Select Interpreter，然后选择您创建的虚拟环境。
- 清理旧环境： 如果您之前在 Python 3.12 环境下尝试安装 Kivy 失败，并且可能遗留了一些不完整的依赖，建议清除该环境或在一个全新的兼容环境中进行安装。
总结
Kivy 在 Python 3.12 环境下安装失败的根本原因是版本兼容性问题。通过选择 Kivy 已知支持的 Python 版本（如 3.11），并结合使用 Python 虚拟环境来隔离项目依赖，可以有效解决此问题。始终推荐为每个 Python 项目创建独立的虚拟环境，这不仅有助于解决版本冲突，还能保持开发环境的整洁和稳定。在等待 Kivy 官方全面支持 Python 3.12 期间，采用此方法是确保 Kivy 开发顺利进行的最佳实践。
