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

bash

# 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.

python

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():

json

{
  "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