{"id":2844,"library":"wmill","title":"Windmill Python Client","description":"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.","status":"active","version":"1.682.0","language":"en","source_language":"en","source_url":"https://github.com/windmill-labs/windmill","tags":["client","workflow","automation","api","windmill"],"install":[{"cmd":"pip install wmill","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for execution.","package":"python","version":">=3.7, <4.0"},{"reason":"Used internally by the Windmill class for HTTP requests.","package":"httpx","optional":true}],"imports":[{"symbol":"wmill","correct":"import wmill"},{"note":"For advanced usage and explicit client instantiation.","symbol":"Windmill","correct":"from wmill import Windmill"},{"note":"For S3 integration helpers.","symbol":"S3Object","correct":"from wmill import S3Object"}],"quickstart":{"code":"import os\nimport wmill\n\ndef main():\n    # When running inside Windmill, WM_TOKEN, BASE_URL, and WORKSPACE\n    # are automatically available via environment variables.\n    # For local development, ensure these are set.\n    # Example: WM_TOKEN=your_token BASE_URL=http://localhost:8000 WORKSPACE=your_workspace python your_script.py\n    try:\n        # Get a resource (e.g., database configuration)\n        db_config = wmill.get_resource('u/user/db_config')\n        print(f\"Retrieved DB config: {db_config}\")\n\n        # Get a variable (e.g., an API key)\n        api_key = wmill.get_variable('u/user/api_key')\n        print(f\"Retrieved API key (first 5 chars): {api_key[:5]}...\")\n\n        # Run another script synchronously and get its result\n        result = wmill.run_script_by_path(\n            'f/scripts/my_helper_script',\n            args={'input_data': 'hello'}\n        )\n        print(f\"Script 'my_helper_script' result: {result}\")\n\n        # Advanced usage: instantiate the client directly\n        client = wmill.Windmill(\n            base_url=os.environ.get('BASE_URL', 'http://localhost:8000'),\n            token=os.environ.get('WM_TOKEN', ''),\n            workspace=os.environ.get('WORKSPACE', 'your_workspace')\n        )\n        user_info = client.user\n        print(f\"Current Windmill user: {user_info.email}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Instantiate `wmill.Windmill()` client separately for each thread or process.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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')`).","message":"The `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.","severity":"breaking","affected_versions":">=1.421.0"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Windmill 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}