Build native applications in Python with declarative, reactive interfaces
Velto is a Python framework for building native graphical applications using declarative components, reactive state, and a shared layout engine. It combines a Python-first development experience with native rendering through Qt, Tkinter, and Kivy—without requiring a web browser for the UI.
Project status: Velto 0.1.x is an early-stage release. APIs, tooling, backend parity, and mobile deployment are actively evolving. Desktop support and mobile deployment have different levels of maturity.
- Declarative Python UI: Describe interfaces with PSX markup.
- Reactive updates: Build stateful components using hooks such as
use_state,use_effect, anduse_ref. - Native backends: Render through Qt, Tkinter, and Kivy.
- Styling and layout: Use HTML-like elements, CSS-like styles, Flex, Grid, and scrolling primitives.
- Native integration: Embed toolkit widgets using
Nativeand extend reactive updates through adapters. - Global state: Integrate Pydux when local component state is not enough.
- CLI: Use the Velto CLI for project setup, execution, and packaging workflows.
The recommended way to create, run, and package a Velto application is through Velto CLI. It initializes the project structure, configures the selected native framework, and provides a consistent development and release workflow.
Use a supported Python installation (Python 3.10–3.14 is a conservative choice; compatibility depends on package versions and the selected backend). A virtual environment is recommended:
python -m venv .venvActivate it on macOS or Linux:
source .venv/bin/activateOr on Windows (PowerShell):
.venv\Scripts\Activate.ps1Then install the desktop tooling:
python -m pip install --upgrade pip
python -m pip install "velto-cli[desktop]"velto init --name my-appThe interactive setup guides you through the available frameworks and project options. To select PySide6 explicitly:
velto init --name my-app --framework pyside6Velto CLI supports desktop framework choices including PySide6, PyQt6, PyQt5, PySide2, Kivy, and Tkinter, subject to their platform and Python compatibility.
cd my-app
velto startEdit the generated main.py and other project files. For example, a simple reactive component looks like this:
import sys
from velto import VeltoContext
from velto.ui import psx, use_state
class CounterApp(VeltoContext):
def render(self):
count, set_count = use_state(0)
return psx("""
<div style="display: flex; flex-direction: column; gap: 16px; padding: 24px;">
<h1>Hello, Velto!</h1>
<p>Build reactive native interfaces with Python.</p>
<button on_click={() => set_count(count + 1)}>
Count is {count}
</button>
</div>
""")
if __name__ == "__main__":
sys.exit(CounterApp().run())The example shows component-local reactive state. PSX updates the affected UI nodes and the selected backend renders the native widgets. Run the application using velto start from the project directory.
For a complete starter project with stylesheets and assets, see examples/hello-world.
From the project directory, build your desktop application:
velto buildTo produce a single executable, where supported:
velto build --onefileFor distribution, use the CLI's platform-aware packaging workflow:
velto bundleThe CLI also provides signing and release tools. See the Velto CLI documentation for packaging formats, settings, prerequisites, and platform-specific behavior.
Note
Velto CLI is in alpha. Desktop development is the supported workflow; Android and iOS packaging are experimental and should not be treated as production-ready.
Velto exposes one application-facing interface while preserving clear responsibilities for each subsystem:
Your Python application
|
velto (facade)
|
+-----------------+----------------+
| | |
Qyro Engine PSX Pydux (optional)
Runtime/lifecycle UI + reactivity Shared state
|
Cinnamon
Layout geometry
|
Native renderer adapters
|
Qt / Tkinter / Kivy
| Component | Responsibility | Repository |
|---|---|---|
| Velto | Public application-facing imports | Neuri-AI/Velto |
| Qyro Engine | Application lifecycle, runtime services, and resource handling | Neuri-AI/qyro |
| PSX / Velto Core | Declarative markup, components, reconciliation, hooks, and native adapters | Neuri-AI/PSX |
| Cinnamon | Shared geometric layout computation used by PSX | Neuri-AI/PSX |
| Pydux | Optional store, reducers, selectors, and state integration | Neuri-AI/Pydux |
| Velto CLI | Project development and packaging commands | Neuri-AI/Velto-CLI |
- Your
VeltoContextprovides the application entry point and lifecycle. - PSX processes markup and component definitions into a virtual UI representation.
- Hooks and reconciliation track state changes and determine which nodes need updating.
- Cinnamon computes the layout geometry for the UI.
- The selected renderer maps the result to native toolkit widgets.
The UI is not rendered as an HTML page inside a browser. Explicit native integrations, such as a web view embedded in an application, are available separately.
from velto import VeltoContext
from velto.ui import psx, component, use_state, use_effect, use_ref
from velto.ui import Flex, Grid, GridItem, Scroll, Text, Native, native_adapter
from velto.runtime import get_resource, is_frozen
# Optional: requires `velto[state]`
from velto.state import configure_store, create_slice, use_dispatch, use_selectorVelto reexports the underlying libraries' public objects rather than maintaining a separate wrapper implementation. Existing applications importing from qyro, psx, or pydux can continue using those APIs.
See the public API reference for the facade contract and integration details.
PSX can mount existing native widgets through the Native component. For reactive widget properties, use a widget-owned update_props(self, props, changed) method or register an adapter with @native_adapter(WidgetType).
from velto.ui import native_adapter
@native_adapter(MyWidget)
def update_my_widget(widget, props, changed):
if "value" in changed:
widget.set_value(props["value"])<Native widget={MyWidget} props={{"value": current_value}} />Native widget construction parameters can also be passed separately. Refer to the native integration contract before using toolkit-specific APIs.
Explore the working examples in this repository:
| Example | Description |
|---|---|
| Hello World | Minimal reactive application |
| Dashboard | Multi-section application layout |
| Pydux login screen | Optional centralized state integration |
| Qt Charts | Native chart integration |
| Chromium browser | Browser component embedded as a native integration |
| WebView app | Web view integration |
| Third-party libraries | Extending applications with external UI libraries |
Velto targets desktop applications on Linux, Windows, and macOS, depending on the selected backend and its available native dependencies.
Android and iOS are areas of ongoing development. Mobile packaging and deployment should not yet be assumed to have the same maturity or compatibility coverage as desktop.
The current repository's package manifest requires Python >=3.10,<3.13.20, while docs/compatibility.md describes a broader 0.1.x certification range. When choosing an installation environment, use the published package metadata and the constraints of your selected backend as the source of truth.
The Velto CLI provides commands for generating and working with projects:
velto init
velto startCLI installation, backend selection, and build options are documented in the CLI repository. Packaging and mobile build support vary by platform and backend.
To contribute to this facade repository:
git clone https://github.com/Neuri-AI/Velto.git
cd Velto
python -m pip install -e ".[pyside6]"
python -m pip install pytest
python -m pytestSome integration tests may require additional backend packages or platform-specific tools.
- Public API and native integration
- Compatibility matrix
- PSX source and documentation
- Qyro Engine
- Velto CLI
- Examples
Contributions, reproducible bug reports, and documentation improvements are welcome. Before submitting a change, review the relevant subsystem repository, provide a minimal reproduction for defects, and run the applicable test suite.
Open an issue for facade-level bugs or feature discussions.
Velto is released under the MIT License. Individual runtime engines, UI bindings, and other dependencies may have their own license obligations; consult NOTICE and the corresponding upstream packages.
