wmill

library1.799.0pypypi✓ verified 24d ago

The `wmill` library is the official Python client for interacting with the Windmill platform. It provides a comprehensive set of functions and utilities to manage Windmill resources, variables, and execute scripts or flows. Designed for both module-level convenience functions and advanced class-based usage, it simplifies automation and workflow orchestration within the Windmill ecosystem. The library is actively maintained with frequent updates, usually on a weekly or bi-weekly cadence.

workflow devops

pip install wmill

package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · WMILL

wmill

workflowpythonv1.799.0

Install

2.5s avg

Import

343ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.799.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.364s · 22.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.322s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

wmill

✓ import wmill

Windmill

✓ from wmill import Windmill

For advanced usage and explicit client instantiation.

S3Object

✓ from wmill import S3Object

For S3 integration helpers.

This quickstart demonstrates how to use the `wmill` client to interact with the Windmill platform. It covers retrieving resources and variables, running other scripts, and direct client instantiation for advanced operations. Authentication is handled automatically within the Windmill environment or via `WM_TOKEN`, `BASE_URL`, and `WORKSPACE` environment variables for local development.

import os import wmill def main(): # When running inside Windmill, WM_TOKEN, BASE_URL, and WORKSPACE # are automatically available via environment variables. # For local development, ensure these are set. # Example: WM_TOKEN=your_token BASE_URL=http://localhost:8000 WORKSPACE=your_workspace python your_script.py try: # Get a resource (e.g., database configuration) db_config = wmill.get_resource('u/user/db_config') print(f"Retrieved DB config: {db_config}") # Get a variable (e.g., an API key) api_key = wmill.get_variable('u/user/api_key') print(f"Retrieved API key (first 5 chars): {api_key[:5]}...") # Run another script synchronously and get its result result = wmill.run_script_by_path( 'f/scripts/my_helper_script', args={'input_data': 'hello'} ) print(f"Script 'my_helper_script' result: {result}") # Advanced usage: instantiate the client directly client = wmill.Windmill( base_url=os.environ.get('BASE_URL', 'http://localhost:8000'), token=os.environ.get('WM_TOKEN', ''), workspace=os.environ.get('WORKSPACE', 'your_workspace') ) user_info = client.user print(f"Current Windmill user: {user_info.email}") except Exception as e: print(f"An error occurred: {e}") if __name__ == '__main__': main()

wmill --version

Debug

Known issues

gotchaThe `wmill` client is not inherently thread-safe or multi-processing safe. When developing multi-threaded or multi-process applications, you must create a separate `wmill.Windmill()` client instance for each thread or process to avoid unexpected behavior.

fix

Instantiate `wmill.Windmill()` client separately for each thread or process.

affects: All versions

breakingThe `wmill.write_s3_file()` function's signature changed in version `1.421.0`. It now requires `content_type` and `content_disposition` as positional arguments, leading to `TypeError` if not provided.

fix

Update calls to `wmill.write_s3_file()` to include `content_type` and `content_disposition` arguments (e.g., `wmill.write_s3_file(s3_obj, content, content_type='application/octet-stream', content_disposition='attachment')`).

affects: >=1.421.0

gotchaFor local development outside the Windmill Web IDE, you must explicitly set environment variables (`WM_TOKEN`, `BASE_URL`, `WORKSPACE`) for the `wmill` client to authenticate and connect to your Windmill instance. Without these, client methods may fail or connect to incorrect endpoints.

fix

Ensure `WM_TOKEN`, `BASE_URL` (e.g., `http://localhost:8000` or your instance URL), and `WORKSPACE` are set in your environment variables before running local scripts that use `wmill`.

affects: All versions

gotchaWindmill automatically resolves Python script dependencies by analyzing top-level `import` statements. It uses a heuristic assuming the import root name matches the PyPI package name. If your package structure deviates (e.g., `import my_lib.sub_module` where the package is `my-library`), automatic resolution might fail.

fix

For non-standard package name to import root mappings, consider using PEP-723 inline script metadata for explicit dependency specification or contributing to Windmill's exception list. Otherwise, ensure top-level imports directly reflect PyPI package names.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'wmill'

The `wmill` library is not installed in your current Python environment.

fix

pip install wmill

Exception: WM_API_URL and WM_API_KEY environment variables must be set or passed as arguments to WindmillClient

The `wmill.client.WindmillClient` requires authentication credentials (API URL and API Key) which were neither provided as arguments nor set as environment variables.

fix

from wmill.client import WindmillClient
client = WindmillClient(api_url="https://app.windmill.dev", api_key="YOUR_API_KEY")
# Alternatively, set WM_API_URL and WM_API_KEY environment variables.

AttributeError: module 'wmill' has no attribute 'run_script'

Functions for managing specific Windmill resources (like scripts, variables, or flows) are located within their respective submodules, not directly under the top-level `wmill` module.

fix

import wmill
wmill.scripts.run(script_path="path/to/script", payload={})

Upgrade

Version history

1.799.0latest on PyPI · released Aug 28, 2026

Audit

Dependencies

pythonrequiredRequired for execution.

httpxoptionalUsed internally by the Windmill class for HTTP requests.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/wmill/ ↗

homepagehttps://windmill.dev ↗

docshttps://windmill.dev ↗