Kivy 3.0 安装完全指南pip 预编译轮子、源码编译、Conda 与开发环境搭建【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy导读本文以 Kivy 官方安装文档为核心系统讲解如何在 Windows、macOS、Linux、*BSD、树莓派RPi、Android、iOS 等平台上安装这款跨平台 Python UI 框架内容覆盖 pip 预编译 wheel 安装、无 wheel 时的源码编译含 SDL 依赖自建流程、预发布与 nightly 轮子、可编辑开发安装、Conda 安装以及kivy[base]、kivy[media]等 extras 选择器的底层含义。读完本文你将能根据自己的平台与 Python 版本选择最合适的安装路径并完成环境验证。本文基于仓库 doc/sources/gettingstarted/installation.rst 编写并以仓库内 pyproject.toml、kivy/init.py、Makefile、kivy/graphics/cgl.pyx 等源码为佐证。当前仓库的 Kivy 主版本为 3.0见 kivy/_version.py完整变更记录见 doc/sources/changelog.rst。平台支持总览与安装方式选择Kivy 官方支持多种平台每个平台的推荐安装方式与打包方式各不相同。下表摘自官方安装文档并补充了仓库中对应文档的路径平台安装方式打包方式Windowspip预编译 wheelPyInstaller见 doc/sources/guide/packaging.rstmacOSpip、Kivy.appKivy.app、PyInstaller见 doc/sources/guide/packaging-osx.rstLinuxpip、PPA—*BSDFreeBSD 等pip源码编译—RPipip32 位系统支持 3.11 预编译 wheel—Androidpython-for-android见 doc/sources/guide/packaging-android.rstpython-for-androidiOSkivy-ios见 doc/sources/guide/packaging-ios.rstkivy-iosAnacondacondaconda-forge—版本前提Kivy 对 Python 版本有明确要求。从仓库 pyproject.toml 的requires-python 3.11及[tool.kivy] python_versions 3.11 - 3.14可以看出当前 Kivy 3.0 官方支持的 Python 版本为 3.11–3.14且 kivy/init.py 会在旧版 Python 上直接输出不支持的错误日志例如 Python 2 会提示升级到 Python 3或降级到 Kivy 1.11.0。使用 pip 安装推荐路径pip 是安装 Kivy 最便捷的方式如果存在预编译 wheel 则直接安装否则 pip 会从源码现场编译例如 *BSD 平台。官方为 Windows、macOS、Linux、RPi 上受支持的 Python 版本提供预编译 wheel若你的 Python 版本过新、wheel 缺失或 wheel 无法正常工作则需要走“从源码安装”的路径。1. 准备终端环境与 pip安装 Kivy 前需确保 Python 与 pip 已预装。打开一个新的终端保证 Python 已加入 PATH先升级 pip、setuptools 与 virtualenvpython -m pip install --upgrade pip setuptools virtualenvLinux 用户可能需要将python替换为python3在虚拟环境之外执行后续命令时可能还需要追加--user标志。2. 创建虚拟环境强烈推荐为 Kivy 项目创建独立的虚拟环境可以避免与其他 Python 版本和包产生安装冲突。官方虽称其为可选但强烈建议执行python -m venv kivy_venv激活虚拟环境每次新开终端都要重新激活激活后提示符前缀会出现(kivy_venv)若未出现则说明激活失败后续命令不会生效Windows 默认 CMDkivy_venv\Scripts\activateWindows 上的 bash 终端如 Git for Windowssource kivy_venv/Scripts/activateLinux / macOSsource kivy_venv/bin/activate3. 安装 Kivy预编译 wheel安装当前稳定版及官方示例包同时安装 Kivy 的最小依赖python -m pip install kivy[base] kivy_examples若需要音视频audio/video支持则改用kivy[base,media]或kivy[full]各选择器的具体含义见下文“依赖与 extras 选择器”一节。无头系统提示使用 Raspberry Pi OS Lite 等基于 Linux 的无头系统时可能需要额外安装系统依赖才能让 Kivy 正常运行例如apt-get install libgl1-mesa-glx libgles2-mesa libegl1-mesa libmtdev1从源码安装当 wheel 不可用如 *BSD、过新或过旧的 Python 版本或 wheel 安装后无法正常运行时需要从源码编译安装。官方文档明确指出macOS、Linux 和 BSD 不再支持通过包管理器apt/brew安装 SDL 依赖因为包管理器提供的 SDL 版本往往过时可能无法与 Kivy 适配官方推荐改用仓库提供的构建脚本从源码自建 SDL 依赖这也是 CI 构建 wheel 所用的同一流程。1. 安装平台系统依赖先按平台安装编译所需的系统依赖官方文档对应章节见 doc/sources/installation/installation-windows.rst、doc/sources/installation/installation-osx.rst、doc/sources/installation/installation-linux.rst、doc/sources/installation/installation-rpi.rst。2. 自建 SDL 依赖Windows 平台无需此步骤官方提供预编译的 SDL 依赖其他平台按以下流程执行。先创建存放自建依赖的目录并进入mkdir kivy-deps-build cd kivy-deps-build按平台下载构建脚本脚本位于仓库tools目录对应文件为 tools/build_macos_dependencies.sh 与 tools/build_linux_dependencies.shmacOScurl -O https://raw.githubusercontent.com/kivy/kivy/master/tools/build_macos_dependencies.sh -o build_kivy_deps.shLinuxcurl https://raw.githubusercontent.com/kivy/kivy/master/tools/build_linux_dependencies.sh -o build_kivy_deps.sh赋予执行权限并运行chmod x build_kivy_deps.sh ./build_kivy_deps.sh脚本会下载并从源码构建 SDL 依赖安装到名为kivy-dependencies的目录中该目录后续会被 Kivy 用于源码构建。OpenGL 后端选项macOSmacOS 上默认使用 ANGLE via Metal 后端提供 OpenGL 支持Apple 已弃用系统 OpenGL 框架。若坚持用 Apple 提供的 OpenGL 框架构建 SDL3可设置USE_LEGACY_OPENGL1 ./build_kivy_deps.sh3. 告知 Kivy 依赖位置KIVY_DEPS_ROOT必须将KIVY_DEPS_ROOT环境变量指向kivy-dependencies目录Kivy 才能找到自建依赖。例如在kivy-deps-build目录内export KIVY_DEPS_ROOT$(pwd)/kivy-dependencies4. 从源码安装稳定版依赖就绪且KIVY_DEPS_ROOT已设置后在虚拟环境中执行--no-binary kivy强制走源码编译python -m pip install kivy[base] kivy_examples --no-binary kivy5. 安装 master 分支最新开发版想安装最新的 cutting-edge 版本可直接从 GitHub 归档安装python -m pip install kivy[base] https://github.com/kivy/kivy/archive/master.zip分支/提交定制替换 URL 的对应部分即可安装不同分支或特定提交。例如stable分支对应https://github.com/kivy/kivy/archive/stable.zip特定提交可用https://github.com/kivy/kivy/archive/3d3e45dda146fef3f4758aea548da199e10eb382.zip这样的提交哈希地址。这尤其适用于测试某个 PR 的修复。ANGLE 后端开关若之前用USE_LEGACY_OPENGL1构建了 SDL3即不使用 ANGLE安装 Kivy 时需显式关闭 ANGLE 后端USE_ANGLE_GL_BACKEND0 python -m pip install kivy[base] kivy_examples --no-binary kivy预发布版本与 Nightly 轮子安装最新的预发布pre-releasewheel给 pip 添加--pre标志即可安装已发布到 PyPI 的预发布版本python -m pip install --pre kivy[base] kivy_examples安装每日 Nightly 轮子Kivy 每天都会为 master 分支的当前开发版本生成快照轮子包含最新改动与实验性修复稳定性风险更高。Nightly 安装需要分两步执行否则 pip 可能忽略服务器上的轮子、退而安装 PyPI 上较旧的预发布版本python -m pip install kivy --pre --no-deps --index-url https://kivy.org/downloads/simple/ python -m pip install kivy[base] --pre --extra-index-url https://kivy.org/downloads/simple/官方在文档中警告使用最新开发版本可能有风险开发中可能遇到问题若发现 bug 请反馈给项目。开发安装可编辑安装 / Editable Install如果你想修改 Kivy 源码、尝试修复 issue 并提交 Pull Request需要先克隆源码再以可编辑方式安装。前置条件已安装 git。git clone https://github.com/kivy/kivy.git cd kivy python -m pip install -e .[dev,full]此后可以自由切换分支、编辑代码并提交 PR。每次修改 Cython 文件.pyx后必须重新编译python setup.py build_ext --inplace在 bash 或 Linux 下也可直接make*BSD Unix 需用 GNU 的gmake替代make。运行测试套件pytest kivy/tests或bash / Linuxmake test仓库 Makefile 中test目标实际执行的是env KIVY_NO_ARGS1 $(PYTEST) kivy/tests并会先清理旧的测试构建产物make style则通过ruff做代码风格检查make hook可安装 pre-commit 钩子。验证安装运行示例 Demo安装完成后应能import kivy。若同时安装了kivy_examples可直接运行官方 showcase 演示Windowspython kivy_venv\share\kivy-examples\demo\showcase\main.pybash / Linux / macOSpython kivy_venv/share/kivy-examples/demo/showcase/main.py*BSD Unixpython3 kivy_venv/share/kivy-examples/demo/showcase/main.py示例目录的代码级定位示例目录的精确路径存放在kivy.kivy_examples_dir属性中。从 kivy/init.py 的实现可以看到该属性按优先级依次探测仓库内examples/目录、sys.exec_prefix/share/kivy-examples、sys.prefix/share/kivy-examples、/usr/share/kivy-examples、/usr/local/share/kivy-examples、~/.local/share/kivy-examples命中即采用。仓库内的 3D 猴子演示位于 examples/3Drendering/main.py同样值得一试。使用 Conda 安装如果你使用 Anaconda 发行版可通过其包管理器 Conda 从 conda-forge 渠道安装conda install kivy -c conda-forge注意官方明确提示使用 Anaconda 时不要用 pip 安装 Kivy除非是源码安装场景——混用可能破坏 conda 的环境一致性。Kivy 依赖体系与 extras 选择器Kivy 的核心提供者provider支持一个或多个后端例如 Windows 上图形后端可选用 glew、angle、sdl3。对窗口、图形、视频、音频等每一类核心能力至少需要安装一个后端才能使用该类别。为了方便安装项目在 pyproject.toml 的[project.optional-dependencies]中定义了extras_require选择器组使安装命令简化为pip install kivy[base,media,tuio]这种形式。官方选择器一览选择器作用baseKivy 运行所需的最小典型依赖不含视频/音频media仅视频/音频依赖使 Kivy 具备媒体播放能力fullKivy 运行的全部典型依赖含视频/音频及大多数可选依赖dev开发模式额外依赖编译头文件、跑测试与构建文档所需不含 base/media/fulltuio使 TUIO 协议可用主要是 oscpy以仓库 pyproject.toml 的实际定义为例base [pillow9.5.0,12]media在 Windows 上安装kivy_deps.gstreamer在 Linux/macOS 且 Python 3.14 时安装ffpyplayerfull则是pillow12.3,13与上述媒体依赖的组合dev包含 pytest 系列、pyinstaller、pre-commit、ruff 等一整套开发工具链。kivy_deps 后端依赖轮子下列选择器安装的是以Kivy_deps命名空间打包的 wheel通常与特定 Kivy 版本配套发布。使用选择器可省去手动指定版本号例如不必写pip install kivy kivy_deps.sdl3x.y.z直接pip install kivy[sdl3]即可自动安装与 Kivy 版本匹配的 sdl3gstreamerGStreamer 视频/音频后端目前仅 Windows 提供。也可用ffpyplayer作为替代。其他平台需自行独立安装。glew/angleOpenGL 后端两者可同时安装目前仅 Windows 提供其他平台无需外部安装。可通过KIVY_GL_BACKEND环境变量选择使用哪个后端。sdl3窗口/图像/音频及可选的 OpenGL后端。仅 Windows 单独提供其他平台已包含在 Kivy 主 wheel 中。KIVY_GL_BACKEND 环境变量与图形后端KIVY_GL_BACKEND控制 OpenGL 后端的运行时选择。从 kivy/graphics/cgl.pyx 的源码注释与实现可以确认可取值包括glUnix 上的默认后端需要系统 gl。glewWindows 上的默认后端需要安装 glew。sdl3Windows/Unix 上在 gl/glew 禁用时的默认后端需要kivy_deps.sdl3。angle_sdl3Windows 上 glew 的替代品需同时安装kivy_deps.sdl3与kivy_deps.angle。anglemacOS 与 iOS 上的后端。mock始终可用实际不做任何绘制。例如在 Windows 上设置KIVY_GL_BACKENDglew默认、angle_sdl3或sdl3来选择图形后端。另外 kivy/graphics/cgl.pyx 还提到KIVY_GL_DEBUG1可记录所有 GL 调用KIVY_GRAPHICSgles可强制使用 OpenGL ES2Android、iOS、RPi、Mali 平台本就默认使用 ES2。Python 术语速览新手须知安装 PythonKivy 用 Python 编写使用前需有可用的 Python 安装。多个 Python 版本可以并存但 Kivy 需要在你想使用的每一个 Python 版本下分别安装为包。安装完成后在控制台执行python --version确认可用。平台专属安装说明见 doc/sources/installation/installation-windows.rst、doc/sources/installation/installation-osx.rst、doc/sources/installation/installation-linux.rst、doc/sources/installation/installation-rpi.rst。命令行基础执行本文中的 pip/wheel 命令需要命令行环境也称 console、terminal、shell、bash且 Python 必须位于 PATH 中。Windows 默认命令行是 cmdWinR输入cmd回车即可打开官方也推荐 Git for Windows 或 MSYS 这类 Linux 风格终端。若 Python 未加入 PATH可用cd临时切换到 Python 安装目录如cd C:\Python37或参考对应平台的 PATH 配置说明。pip 与 wheel 是什么pipPython 包管理器python install package。wheel.whl文件已编译好的分发包安装时无需额外编译步骤而源码安装的包如 Kivy可能需要编译。当 wheel 在 PyPI 上可用时执行python -m pip install kivy会自动找到合适的 wheel也可以直接安装本地 wheel 文件python -m pip install C:\Kivy-1.9.1.dev-cp27-none-win_amd64.whlNightly wheel 是什么Kivy 每天为 master 分支的开发版本生成一份快照 wheel即 nightly wheel其中包含全部最新改动含实验性修复与上一个稳定版形成对照。安装方法见上文“安装每日 Nightly 轮子”一节官方同样提示开发版存在使用风险。小结如何选择安装路径常规开发python -m pip install kivy[base] kivy_examples配合python -m venv虚拟环境最省心需要音视频播放改用kivy[base,media]或kivy[full]Windows 上图形异常通过KIVY_GL_BACKEND在glew/angle_sdl3/sdl3间切换平台无 wheel如 *BSD或 Python 版本过新按“从源码安装”流程自建 SDL 依赖并设置KIVY_DEPS_ROOT参与开发/提交 PRgit clonepip install -e .[dev,full]改 Cython 后make重新编译用pytest kivy/tests验证Anaconda 用户conda install kivy -c conda-forge避免混用 pip。安装完成后用import kivy或运行kivy_examples的 showcase 演示确认环境就绪即可开始你的第一个 Kivy 应用。【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
