Wox Plugin Python

This package provides type definitions for developing Wox plugins in Python.

Requirements

Python >= 3.8 (defined in pyproject.toml)
Python 3.12 recommended for development (defined in .python-version)

Installation

# Using pip
pip install wox-plugin

# Using uv (recommended)
uv add wox-plugin

Usage

This example returns QueryResponse, so the plugin's plugin.json should set MinWoxVersion to 2.0.4 or newer. Return list[Result] directly if you need the same plugin build to run on older Wox releases.

from wox_plugin import Query, QueryResponse, Result, Context, PluginInitParams, WoxImage

class MyPlugin:
    async def init(self, ctx: Context, params: PluginInitParams) -> None:
        self.api = params.API
        
    async def query(self, ctx: Context, query: Query) -> QueryResponse:
        # Your plugin logic here
        results = []
        results.append(
            Result(
                title="Hello Wox",
                sub_title="This is a sample result",
                icon=WoxImage.new_emoji("🔍"),
                score=100
            )
        )
        return QueryResponse(results=results)

# MUST HAVE! The plugin class will be automatically loaded by Wox
plugin = MyPlugin()

Returning list[Result] directly is deprecated. The Python host still accepts it for compatibility with older Wox releases. Use QueryResponse only when plugin.json declares MinWoxVersion >= 2.0.4 so results, refinements, and layout hints are carried together.

When a plugin needs to control the preview width or grid layout, set QueryResponse.layout.result_preview_width_ratio or QueryResponse.layout.grid_layout. The older resultPreviewWidthRatio and gridLayout metadata features are deprecated because they can only describe static plugin or command defaults.

Saving Settings

set_setting() requires Wox >= 2.4.0 and accepts a SetSettingOption. Set is_local=True when a value must stay on the current device and remain outside Cloud Sync. The older save_setting() method remains available for plugins targeting Wox releases before 2.4.0, but is deprecated for new integrations.

Query Requirements

Plugins can declare settings that must be configured before Wox calls query():

{
  "QueryRequirements": {
    "AnyQuery": [
      {
        "SettingKey": "apiKey",
        "Validators": [{ "Type": "not_empty" }],
        "Message": "i18n:my_plugin_api_key_required"
      }
    ],
    "QueryWithoutCommand": [],
    "QueryWithCommand": {
      "download": [
        {
          "SettingKey": "downloadPath",
          "Validators": [{ "Type": "not_empty" }]
        }
      ]
    }
  }
}

License

MIT

Static HTML preview

Use WoxPreviewType.WEBVIEW with a JSON-encoded html field. No HTTP server or temporary HTML file is needed; there is no separate html preview type.

import json
from wox_plugin import WoxPreview, WoxPreviewType

preview = WoxPreview(
    preview_type=WoxPreviewType.WEBVIEW,
    preview_data=json.dumps({
        "html": '<!doctype html><html><body><h1 style="color:teal">Hello Wox</h1></body></html>'
    }),
)
# Assign preview to Result(preview=preview, ...).

Set either html or url. Optional JSON fields are injectCss, userAgent, cacheDisabled, and cacheKey (defaults to the URL or HTML). Inline HTML has no plugin-relative base URL: embed CSS/images or use absolute resource URLs. This is browser content, not sanitized Markdown; use html.escape for untrusted text before interpolation.

Structured queries

QueryHint and QueryElement are exported by wox_plugin. Declare a suffix template in MetadataCommand.query_hint, read query.query_hint.elements, and use ChangeQueryParam(query_type=QueryType.INPUT, query_hint=...) for a complete instance. When structure is absent, retain the existing query.search parsing path. See the query model and Python examples. This is a development-build capability; verify release and SDK support before setting a distributable plugin's minimum versions.

Metadata

Release files for wox-plugin 0.0.85

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wox-plugin 0.0.85
File	Size	Uploaded
wox_plugin-0.0.85.tar.gz	79.8 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for wox-plugin 0.0.85
File	Interpreter	ABI	Platform	Reset
wox_plugin-0.0.85-py3-none-any.whl 59.8 kB Sep 6, 2026	Python 3	none	any	Details

Total release size: 139.7 kB

Release files / wox_plugin-0.0.85.tar.gz

Download URL	wox_plugin-0.0.85.tar.gz
Size	79.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`503782eb3f969fecbb28660ff2d95904a9657295e570a9b789ed96b656b05832`
BLAKE2b-256 checksum How to use checksums	`3ab36c571846ab9bdadcd9641b71934c78364d6c7c5e80603d3c6f72d7e82886`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.10.20`

Release files / wox_plugin-0.0.85-py3-none-any.whl

Download URL	wox_plugin-0.0.85-py3-none-any.whl
Size	59.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5810b9d78e98df3c6ce13f2fd082d8676a715e35fee9829b570167a6dbc25e2a`
BLAKE2b-256 checksum How to use checksums	`086a084e14a002d34ac14798f596890d7b153eb01c9faf80d8412941f747a53d`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.10.20`