{"id":8367,"library":"ob-metaflow-stubs","title":"Metaflow Stubs","description":"ob-metaflow-stubs provides type stubs for the Metaflow library, enhancing static analysis and developer experience for Metaflow users. Metaflow is a human-centric framework for building and managing real-life AI and ML systems, originally developed at Netflix and now supported by Outerbounds. It streamlines the entire development lifecycle from rapid prototyping to production deployments, enabling teams to iterate quickly and deliver robust systems efficiently. The library is actively maintained with frequent patch releases, aligning with the core Metaflow project's release cadence.","status":"active","version":"6.0.12.28","language":"en","source_language":"en","source_url":"https://github.com/Netflix/metaflow","tags":["metaflow","stubs","type hints","mlops","data science","workflow automation","python","outerbounds"],"install":[{"cmd":"pip install ob-metaflow-stubs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package provides type stubs for the 'metaflow' library; 'metaflow' is required for runtime functionality.","package":"metaflow","optional":false}],"imports":[{"symbol":"FlowSpec","correct":"from metaflow import FlowSpec"},{"symbol":"step","correct":"from metaflow import step"},{"symbol":"Parameter","correct":"from metaflow import Parameter"},{"symbol":"current","correct":"from metaflow import current"},{"note":"While `@retry` is a decorator, it's typically imported directly from the top-level `metaflow` package for consistency with other core components.","wrong":"from metaflow.decorators import retry","symbol":"retry","correct":"from metaflow import retry"}],"quickstart":{"code":"from metaflow import FlowSpec, step\n\nclass HelloFlow(FlowSpec):\n    \"\"\"A simple Metaflow flow to validate installation.\"\"\"\n\n    @step\n    def start(self):\n        print(\"HelloFlow is starting.\")\n        self.message = \"Metaflow says: Hi!\"\n        self.next(self.hello)\n\n    @step\n    def hello(self):\n        print(self.message)\n        self.next(self.end)\n\n    @step\n    def end(self):\n        print(\"HelloFlow is all done.\")\n\nif __name__ == \"__main__\":\n    HelloFlow()","lang":"python","description":"This 'Hello World' example defines a basic Metaflow flow with three steps: `start`, `hello`, and `end`. It demonstrates defining steps with `@step` and connecting them with `self.next()`. Run this script using `python your_flow_name.py run` in your terminal to execute the flow locally."},"warnings":[{"fix":"Always review the GitHub release notes of the main `metaflow` library (Netflix/metaflow) before upgrading to understand specific breaking changes and migration steps that might affect stub usage.","message":"While Metaflow prioritizes backward compatibility, minor breaking changes can occur in patch versions, especially those addressing bug fixes or internal architectural improvements. These can impact how stubs align with the runtime library.","severity":"breaking","affected_versions":"All versions"},{"fix":"Explicitly declare all external Python dependencies using the `@pypi` or `@conda` decorators on your `FlowSpec` class or individual `@step` methods to ensure reproducibility and correct execution in remote environments. For example: `@pypi(packages={'scikit-learn': '1.0.2'})`.","message":"When scaling Metaflow flows to remote compute environments (e.g., AWS Batch, Kubernetes), locally `pip install`'d or `conda install`'d third-party dependencies are not automatically available. This can lead to runtime errors even if your local environment with stubs is correct.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install and configure Windows Subsystem for Linux (WSL) and then install Metaflow (and its stubs) within the WSL environment.","message":"Metaflow does not offer native support for Windows operating systems. Users on Windows must utilize the Windows Subsystem for Linux (WSL) to install and run Metaflow and its stubs, as it relies on a *nix-like environment.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid mutable default arguments. Initialize mutable objects (like lists or dictionaries) inside the step method, for example, `items = [] if items is None else items`.","message":"Using mutable default arguments in `@step` method signatures (e.g., `items=[]`) can lead to unexpected shared state across different task executions, violating Metaflow's reproducibility principles.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure that `self.next(next_step_method)` is called at the end of every step (except for the final `end` step) to define the flow's execution graph.","message":"Failing to call `self.next()` at the end of a step will terminate the flow execution at that step, preventing subsequent steps from running, even if the logic within the current step completes successfully.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `@pypi` or `@conda` decorators with the necessary packages and their versions to the `FlowSpec` or the specific `@step` method. Ensure consistency across environments.","cause":"A required Python package for a step was not found or had a version conflict in the execution environment, particularly when running remotely without explicitly declared dependencies.","error":"Error: MetaflowStepDependencyError: Step 'step_name' failed due to missing or incompatible dependencies."},{"fix":"Ensure the variable is assigned to `self.variable_name` in the producing step and that `self.next()` correctly transitions to the consuming step. When inspecting past runs, use the Metaflow Client API, `from metaflow import current`, to reliably access artifacts.","cause":"The artifact `self.variable` from a prior step was not properly set or was not serialized/deserialized correctly, or an attempt was made to access it from an unsupported context (e.g., before the preceding step completed).","error":"AttributeError: 'NoneType' object has no attribute 'some_attribute' or similar when accessing self.variable from a previous step."},{"fix":"Convert non-serializable objects into a serializable format (e.g., JSON, string, bytes, or a well-known data structure like a pandas DataFrame) before assigning them to `self.` attributes.","cause":"An attempt was made to store a non-serializable Python object directly as a Metaflow artifact (instance variable `self.xyz`), which Metaflow attempts to persist between steps.","error":"TypeError: Object of type MyObject is not JSON serializable"}]}