{"id":4690,"library":"prefect-shell","title":"Prefect Shell","description":"Prefect Shell provides integrations for executing shell commands within Prefect flows. It allows users to embed shell scripts and commands directly into their data pipelines, leveraging Prefect's orchestration capabilities like logging, retries, and observability. This library is part of the Prefect ecosystem, currently at version 0.3.5, and is actively maintained with regular updates as part of the broader Prefect project.","status":"active","version":"0.3.5","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-shell","tags":["prefect","shell","orchestration","workflow","task","integration"],"install":[{"cmd":"pip install \"prefect[shell]\"","lang":"bash","label":"Recommended installation (includes Prefect)"},{"cmd":"pip install prefect-shell","lang":"bash","label":"Install only prefect-shell"}],"dependencies":[{"reason":"prefect-shell is an integration for the Prefect workflow orchestration framework and requires Prefect core to function.","package":"prefect"}],"imports":[{"symbol":"ShellOperation","correct":"from prefect_shell import ShellOperation"},{"symbol":"flow","correct":"from prefect import flow"}],"quickstart":{"code":"from prefect import flow\nfrom prefect_shell import ShellOperation\n\n@flow\ndef run_simple_command():\n    # For short-running operations, use the .run() method\n    result = ShellOperation(commands=[\"echo Hello from Prefect Shell!\"]).run()\n    print(f\"Command output: {result.stdout.strip()}\")\n\n    # For longer-running operations or capturing structured output, use a context manager\n    with ShellOperation(\n        commands=[\"ls -l /tmp\"],\n        working_dir=\"/tmp\"\n    ) as list_files_operation:\n        process = list_files_operation.trigger()\n        process.wait_for_completion()\n        output_lines = process.fetch_result()\n        print(\"\\nFiles in /tmp:\")\n        for line in output_lines:\n            print(line.strip())\n\nif __name__ == \"__main__\":\n    run_simple_command()","lang":"python","description":"This quickstart demonstrates how to define a Prefect flow that executes shell commands using `ShellOperation`. It shows both the `.run()` method for simple, short commands and the context manager pattern (`with ShellOperation(...) as op: ...`) for long-running operations or when explicit output capture is required."},"warnings":[{"fix":"Upgrade your Prefect core installation to Prefect 2.x (e.g., `pip install -U prefect`) or ensure your environment uses Prefect 2.x if migrating from an older Prefect 1.x project.","message":"Prefect 2.x changed the core API from Prefect 1.x. `prefect-shell` is designed specifically for Prefect 2 and is not compatible with Prefect 1. Ensure your Prefect core installation is version 2.0 or higher.","severity":"breaking","affected_versions":"<2.0.0 of Prefect core"},{"fix":"For synchronous, short commands and immediate results: `result = ShellOperation(commands=['command']).run()`. For asynchronous execution, explicit process management, or long-running tasks: `with ShellOperation(...) as op: process = op.trigger(); process.wait_for_completion(); output = process.fetch_result()`.","message":"When using `ShellOperation`, calling `.run()` is suitable for short, synchronous commands. For long-running processes or when needing to manage the subprocess lifecycle (e.g., waiting for completion, capturing output), use the context manager pattern (`with ShellOperation(...)`) combined with `.trigger()` and `.wait_for_completion()`, followed by `.fetch_result()` to get output. Directly calling `.run()` inside a flow will execute synchronously and may block.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run `prefect block register -m prefect_shell` in your terminal after installing the library to make its block types available in the Prefect UI.","message":"To use `ShellOperation` as a Prefect block type (e.g., for creating and managing shell commands directly in the Prefect UI), you must explicitly register the blocks after installation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}