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.
pip install "prefect[shell]"Verified import paths — ran on the pinned version, not inferred.
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.
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.
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()`.
Run `prefect block register -m prefect_shell` in your terminal after installing the library to make its block types available in the Prefect UI.
First, ensure `prefect-shell` is up-to-date by running `pip install -U prefect-shell`. Then, change the import statement to `from prefect_shell import ShellOperation`.
Install the `prefect-shell` collection using pip: `pip install "prefect[shell]"`. Ensure you are installing it into and running your code from the correct Python environment.
Debug the specific shell command(s) by running them directly outside of Prefect to identify the root cause of their failure (e.g., incorrect syntax, missing dependencies, insufficient permissions, or environment issues). For Prefect agents, ensure the agent process has the necessary permissions and access to files or directories referenced by the command.
Migrate from `shell_run_command` to the `ShellOperation` class, which is the recommended and more robust way to execute shell commands in Prefect flows. For example, replace `shell_run_command(command='...')` with `ShellOperation(commands=['...']).run()`.