控制环境¶

许多环境变量可用于控制Kivy的初始化和行为。

例如，为了将文本渲染限制为PIL实现：：

$ KIVY_TEXT=pil python main.py

环境变量应在导入 kivy 之前设置：

import os
os.environ['KIVY_TEXT'] = 'pil'
import kivy

路径控制¶

在 1.0.7 版本加入.

您可以控制配置文件、模块和Kivy数据所在的默认目录。

KIVY_DATA_DIR

Kivy 数据的位置，默认为 <kivy 路径>/data。

KIVY_MODULES_DIR

Kivy 模块的位置，默认为 <kivy path>/modules。

KIVY_HOME

Kivy 主目录的位置。此目录用于本地配置，必须位于可写的位置。

默认为：

桌面：<用户主目录>/.kivy
Android：<安卓应用路径>/.kivy
iOS：<用户主目录>/Documents/.kivy

在 1.9.0 版本加入.

KIVY_DESKTOP_PATH_ID

为桌面平台目录设置面向用户、可读的应用程序标题。这使得最终用户在浏览文件系统时，能够轻松识别哪个应用程序拥有哪些目录。

重要提示： 设置此变量将为包含配置和日志文件的 .kivy 目录创建一个**应用特定**的位置。如果不设置 KIVY_DESKTOP_PATH_ID，配置和日志将存放在所有 Kivy 应用共享的全局 .kivy 目录中。这允许多个 Kivy 应用拥有独立的配置和日志目录。

设置后，该标识符会为文件系统安全性进行规范化处理（如 /\:*?"<>| 等无效字符会被替换为下划线），并用于构建 KIVY_HOME、user_data_dir 和 user_cache_dir 路径。

使用此功能显示一个清晰、易识别的名称，如“我的照片编辑器”或“公司应用名称”，而不是技术标识符。

如果在桌面平台上未设置，路径构造将回退到使用 App.name（从您的 App 类名称派生的字符串）。系统会记录一条警告，建议您设置 KIVY_DESKTOP_PATH_ID 以提高最终用户的清晰度。

优先于KIVY_HOME环境变量和虚拟环境检测。在移动平台（iOS、Android）上忽略，因为这些平台的文件系统不允许用户浏览。

移动开发者注意：如果您在桌面平台上开发移动应用，可以将`KIVY_DESKTOP_PATH_ID`设置为任意值以抑制警告。该变量对您的移动应用不会产生任何影响，但设置它可以避免在开发过程中出现警告。

当设置为“My Photo Editor”时的示例路径：

Windows：%APPDATA%\\My_Photo_Editor\\.kivy
macOS：~/Library/Application Support/My_Photo_Editor/.kivy
Linux：~/.local/share/My_Photo_Editor/.kivy

在 3.0.0 版本加入.

KIVY_SDL3_PATH

如果设置了此路径，则在编译kivy时将使用该路径下的SDL3库和头文件，而非系统范围内安装的版本。要在运行kivy应用时使用相同的库，必须将此路径添加到PATH环境变量的开头。

在 3.0.0 版本加入.

警告

此路径对于Kivy的编译是必需的，但对于程序执行则不是必需的。

KIVY_SDL3_FRAMEWORKS_SEARCH_PATH

如果设置了此路径，编译kivy时将使用该路径下的SDL3框架，而非系统范围内安装的框架。

该路径仅在macOS上使用，且必须包含SDL3.framework、SDL_image.framework、SDL_mixer.framework和SDL_ttf.framework。

在 3.0.0 版本加入.

警告

此路径对于Kivy的编译是必需的，但对于程序执行则不是必需的。

KIVY_DEPS_ROOT

如果设置，在构建过程中，Kivy 将使用此目录作为根目录来搜索（目前仅限 SDL）依赖项。请注意，如果设置了 KIVY_SDL3_PATH 或 KIVY_SDL3_FRAMEWORKS_SEARCH_PATH，则将优先使用它们。

在 2.2.0 版本加入.

警告

此路径对于Kivy的编译是必需的，但对于程序执行则不是必需的。

配置¶

KIVY_USE_DEFAULTCONFIG

如果环境中存在此名称，Kivy 将不会读取用户配置文件。

KIVY_NO_CONFIG

如果设置了此项，将不会读取或写入任何配置文件。这也适用于用户配置目录。

KIVY_NO_FILELOG

如果设置了此项，日志将不会打印到文件中。

KIVY_NO_CONSOLELOG

如果设置了此项，日志将不会打印到控制台。

KIVY_NO_ARGS

如果设置为（'true'、'1'、'yes'）中的任意一个，命令行中传入的参数将不会被Kivy解析和使用。也就是说，你可以安全地编写脚本或应用，使用自己的参数，而无需使用`--`分隔符。

import os
os.environ["KIVY_NO_ARGS"] = "1"
import kivy

在 1.9.0 版本加入.

KCFG_section_key

如果检测到这样的格式环境名称，它将被映射到Config对象。它们仅在导入`kivy`时加载一次。可以通过`KIVY_NO_ENV_CONFIG`禁用此行为。

import os
os.environ["KCFG_KIVY_LOG_LEVEL"] = "warning"
import kivy
# during import it will map it to:
# Config.set("kivy", "log_level", "warning")

在 1.11.0 版本加入.

KIVY_NO_ENV_CONFIG

如果设置了该选项，则不会有环境键映射到配置对象。如果未设置，任何 KCFG_section_key=value 格式的环境变量都将映射到 Config。

在 1.11.0 版本加入.

将核心限制为特定实现¶

kivy.core 会尝试为您的平台选择最佳可用实现。为了测试或自定义安装，您可能希望将选择器限制为特定的实现。

你可以通过逗号分隔的列表指定多个提供者，以设置优先级顺序。Kivy 将按列表顺序尝试每个提供者，并使用第一个成功初始化的提供者。例如：：

$ KIVY_IMAGE=sdl3,pil python main.py

或者在Python中：

import os
os.environ['KIVY_IMAGE'] = 'sdl3,pil'
import kivy

这将首先尝试使用sdl3图像提供器，若sdl3不可用或文件格式不受其支持，则回退至pil。

一些核心模块也支持按实例选择提供者，允许在同一应用程序中不同的对象使用不同的提供者实现。详情请参阅以下模块：

kivy.core.audio_output - 按实例选择音频提供器
kivy.core.image - 实例级图像提供器选择
kivy.core.text - 按实例选择文本提供器

KIVY_WINDOW

用于创建窗口的实现。

值：sdl3、x11、egl_rpi

KIVY_TEXT

用于渲染文本的实现方式。

值：sdl3、pil、sdlttf

KIVY_VIDEO

用于渲染视频的实现。

值：gstplayer、ffpyplayer、ffmpeg、android、null

KIVY_AUDIO_OUTPUT

用于播放音频的实现。

值：sdl3、gstplayer、ffpyplayer、avplayer

KIVY_IMAGE

用于读取图像的实现。

值：sdl3、pil、imageio、tex、dds

在 2.0.0 版本发生变更.

移除了 GPL 的 gif 实现。

KIVY_CAMERA

用于读取摄像头的实现。

值：avfoundation、android、opencv

KIVY_SPELLING

用于拼写检查的实现。

值：enchant、osxappkit

KIVY_CLIPBOARD

用于剪贴板管理的实现。

值：sdl3、dummy、android

度量（Metrics）¶

KIVY_DPI: 如果设置了该值，它将用于 Metrics.dpi。

在 1.4.0 版本加入.
KIVY_METRICS_DENSITY: 如果设置了该值，它将用于 Metrics.density。

在 1.5.0 版本加入.

KIVY_METRICS_FONTSCALE

如果设置了该值，它将用于 Metrics.fontscale。

在 1.5.0 版本加入.

图形。¶

KIVY_GL_BACKEND

要使用的OpenGL后端。参见 cgl。

KIVY_GL_DEBUG

是否记录OpenGL调用。参见 cgl。

KIVY_GRAPHICS

是否使用OpenGL ES2。参见:mod:~kivy.graphics.cgl。

KIVY_GLES_LIMITS

是否强制执行GLES2限制（默认启用，或设置为1）。如果设置为false，Kivy将不会真正兼容GLES2。

以下是设置为 true 时可能导致的不兼容性列表。

网格索引	如果为真，网格中的索引数量将限制为65535。
纹理位块传输	在将数据（颜色和缓冲区）格式写入纹理时，必须与创建纹理时使用的格式保持一致。在桌面平台上，驱动程序能正确处理不同颜色格式的转换，而在Android平台上，大多数设备无法完成此转换。参考：https://github.com/kivy/kivy/issues/1600

在 1.8.1 版本加入.

KIVY_BCM_DISPMANX_ID

更改使用egl_rpi窗口提供程序时默认的Raspberry Pi显示器。可用值列表可在`vc_dispmanx_types.h`中查看。默认值为0：

0: DISPMANX_ID_MAIN_LCD
1: DISPMANX_ID_AUX_LCD
2: DISPMANX_ID_HDMI
3: DISPMANX_ID_SDTV
4: DISPMANX_ID_FORCE_LCD
5: DISPMANX_ID_FORCE_TV
6: DISPMANX_ID_FORCE_OTHER

KIVY_BCM_DISPMANX_LAYER

在使用egl_rpi窗口提供程序时，更改默认的Raspberry Pi dispmanx层。默认值为0。

在 1.10.1 版本加入.

事件循环¶

KIVY_EVENTLOOP

当应用以异步方式运行时，应使用哪个异步库。参见 kivy.app 中的示例用法。

'asyncio'：当应用以异步方式运行时，以及标准: 应使用asyncio库包。若未设置，则为默认值。
'trio'：当应用以异步方式运行时，且使用 trio: 应使用该包。

在 2.0.0 版本加入.

« Kivy 基础

配置Kivy »

Version

Quick search

目录

控制环境¶

路径控制¶

配置¶

将核心限制为特定实现¶

度量（Metrics）¶

图形。¶

事件循环¶