PyTauri Wheel¶

The pytauri-wheel is built using the method described in tutorial/build-wheel to provide a precompiled pytauri.EXT_MOD. This means you can use pytauri without writing any Rust code and needing a Rust compiler.

Installation¶

PyPi¶

Prerequisites¶

windowslinuxmacOS

Install WebView2 by visiting the WebView2 Runtime download section. Download the "Evergreen Bootstrapper" and install it.

As mentioned in https://tauri.app/distribute/debian/#debian:

libwebkit2gtk-4.1-0
libgtk-3-0
libappindicator3-1

Nothing

Wheel¶

We provide precompiled Wheels for the following platforms and supported Python versions:

OS	Arch
windows-2022	x64
windows-11	arm64¹
manylinux_2_35	x64, arm64
macOS-13	intel
macOS-14	arm64

pip install "pytauri-wheel == 0.8.*"  # (1)!

This is the version at the time of writing this tutorial. There may be a newer version of pytauri available when you use it.

Sdist¶

If the above platform and Python version requirements are not met, the Wheel will be automatically built (compiled) from the source distribution when installing from pypi.

This requires you to meet the tutorial/#prerequisites.

Usage¶

The development experience of pytauri-wheel is almost the same as Rust tauri. You can find a complete example in examples/tauri-app-wheel.

Tauri Config¶

First, we need to create a Tauri.toml, refer to https://tauri.app/develop/configuration-files/#tauri-config:

/Tauri.toml

"$schema" = "https://schema.tauri.app/config/2"
productName = "pytauri-wheel-app"
version = "0.1.0"
identifier = "com.pytauri-wheel-app.app"

[build]
frontendDist = "./frontend"

[app]
withGlobalTauri = true

[[app.windows]]
title = "pytauri-wheel-app"
width = 800
height = 600

Tip

pytauri-wheel also support tauri.conf.json, tauri.conf.json5, tauri.linux.conf.json and etc.

Capabilities¶

Refer to：

Create the following capabilities file to enable ipc permissions:

/capabilities/default.toml

# "$schema" = "..."  # we do not support this feature yet
identifier = "default"
description = "Capability for the main window"
windows = ["main"]
permissions = [
    "core:default",
    "pytauri:default", # need for pytauri ipc
    "dialog:default"
]

Tip

pytauri-wheel also support json and json5 capabilities files.

PyTauri Wheel App¶

The final step, refer to:

/main.py

import sys
from os import environ
from pathlib import Path

from anyio.from_thread import start_blocking_portal
from pytauri import Commands
from pytauri_wheel.lib import builder_factory, context_factory

SRC_TAURI_DIR = Path(__file__).parent.absolute()
"""In rust tauri project, it's usually `src-tauri` dir.

📁 {SRC_TAURI_DIR}/
├── 📁 capabilities/
├── 📄 tauri.conf.json
└── ...
"""

DEV_SERVER = environ.get("DEV_SERVER")
"""Whether to use frontend dev server to serve frontend assets.

e.g, `Vite` dev server on `http://localhost:1420`.
"""

commands = Commands()


@commands.command()
async def greet() -> str:
    return sys.version


if DEV_SERVER is not None:
    # ref: <https://tauri.app/reference/config/#frontenddist-1>
    tauri_config = {
        "build": {
            "frontendDist": DEV_SERVER,
        },
    }
else:
    tauri_config = None


def main() -> int:
    with start_blocking_portal("asyncio") as portal:  # or `trio`
        app = builder_factory().build(
            context=context_factory(SRC_TAURI_DIR, tauri_config=tauri_config),
            invoke_handler=commands.generate_handler(portal),
        )
        exit_code = app.run_return()
        return exit_code


if __name__ == "__main__":
    sys.exit(main())

Note

The frontend assets directory must the same as the [build].frontendDist in Tauri.toml.

/frontend/index.html

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>PyTauri-Wheel-App</title>
    </head>
    <body>
        <button onclick="greet()">Click me</button>
        <script>
            // 🤓 NOTE: you must set `[app.withGlobalTauri] = true` in `Tauri.toml,
            // or you can't use `window.__TAURI__` in the frontend.
            async function greet() {
                const message =
                    await window.__TAURI__.pytauri.pyInvoke("greet");
                alert(message);
            }
        </script>
    </body>
</html>

You get following directory structure:

📁 {SRC_TAURI_DIR}
├── 📁 capabilities
│   └─── 📄 default.toml
├── 📁 frontend
│   └─── 📄 index.html
├── 📄 Tauri.toml
└── 📄 main.py

Then run the app:

python main.py

Development Mode¶

If you want to use frontend dev server such as vite in development, or you want to dynamically/programmatically set tarui config, please refer to pytauri_wheel.lib.context_factory(tauri_config)

PyTauri Plugins¶

pytauri-wheel enables all pytauri plugin features.

As long as you have completed the Python and frontend initialization steps described in tutorial/using-plugins:

Registering the plugin from Python
Adding the required permissions to your capabilities file

you can use plugins in both Python and the frontend.

For example, the tauri-plugin-dialog can be used in the frontend as follows:

import { ask } from '@tauri-apps/plugin-dialog';
// when using `"withGlobalTauri": true`, you may use
// const { ask } = window.__TAURI__.dialog;

Best Practices¶

Although the above example uses pytauri-wheel as a single-file script (python main.py), we strongly recommend that you organize your project in the standard pyproject.toml way as shown in examples/tauri-app-wheel, and generate a venv standalone² executable via [project.scripts] / [project.gui-scripts] (example).

Some Tauri APIs/plugins (such as tauri-plugin-deep-link and tauri-plugin-single-instance) assume your app is a standalone² executable, rather than all scripts sharing the same python(.exe) executable.

Only Python >= 3.11 supports arm64 on Windows, refer to setup-python and python-build-standalone. ↩
Do not confuse this with the pytauri standalone app described in tutorial/build-standalone. Executables generated via [project.scripts] / [project.gui-scripts] depend on the virtual environment and are not portable/distributable. ↩↩