Skip to content

[tool.kivy] reference

[tool.kivy] holds the settings that every target shares. Each target also needs its own overlay table, such as [tool.kivy.android]; [tool.kivy] alone does not configure a target. For how the tables fit together, see Project configuration.

kivyforge reads the app's name and version from [project], and its dependencies from [project].dependencies. The version can be dynamic, taken from git by your build backend; see Set the app version.

Preview

This paragraph describes behavior that is on main but not yet in a released version. It will ship in a future release.

kivyforge also writes the app's package metadata from [project]: its name, version and entry points ([project.scripts], [project.gui-scripts] and [project.entry-points]); see Read your package metadata inside the app. So it checks them as build backends do, and each of these is a config error at the line that breaks it:

  • [project].name is not a valid project name: ASCII letters and digits, with ., _ or - only between them.
  • [project.entry-points] holds a console_scripts or gui_scripts group. Use [project.scripts] and [project.gui-scripts].
  • A group holds a nested table, usually a dotted group name without quotes: write [project.entry-points."myapp.plugins"].
  • A group name isn't words of letters, digits and underscores joined by dots.
  • An entry point name contains =, starts with [, or starts or ends with whitespace.

Entry points must be declared in [project]. A setuptools project that declares them only in setup.cfg or setup.py fails to build with KF-METADATA-ENTRY-POINTS-OUTSIDE-PROJECT.

Keys

Key Type Default Description
app_dir string required Directory that contains your Python source, relative to pyproject.toml. It must be a subdirectory such as "src". The project root ("."), an empty string, an absolute path, and a path outside the project are rejected.
entry_point string "main" Module to run at startup, as a dotted Python name resolved inside app_dir. For example, "main" runs src/main.py and "pkg.start" runs src/pkg/start.py.
display_name string [project].name The app name shown to users. Each platform maps it to its own field, for example CFBundleDisplayName on iOS and android:label on Android.
orientation list of string ["portrait"] Allowed screen orientations. Valid values: portrait, portrait-upside-down, landscape-left, landscape-right. The list must not be empty.

kivyforge rejects any key under [tool.kivy] that it doesn't recognize, including keys in the platform overlays. The error names the key and its line, and suggests the closest valid key, for example:

Error: unknown key 'deployment_targt' in [tool.kivy.ios] (line 14)
  hint: did you mean 'deployment_target'? kivyforge does not read this key, so it would have no effect. [...]

The exceptions are tables whose keys belong to another tool, such as [tool.kivy.ios.info_plist] and [tool.kivy.android.gradle_properties], and a table for a platform that kivyforge doesn't support yet, such as [tool.kivy.web], which is ignored.

Example

[tool.kivy]
display_name = "Dice Roller"
app_dir = "src"
entry_point = "main"
orientation = ["portrait"]

How entry_point runs

kivyforge adds app_dir to sys.path and runs entry_point as __main__ on every platform, the same as python -m. As a result:

  • An if __name__ == "__main__": block in the module runs.
  • Calling App().run() at the top level of the module also works.
  • If entry_point names a package rather than a module, the package needs a __main__.py.

Icons and splash screens

Each platform needs its own icon sizes and formats, so you declare icons and splash screens in the platform overlays, not in [tool.kivy]. See the Android, iOS, macOS, Windows, and Linux overlay references.

What's next