Install & Compatibility
Where this runs
tested against v2.19.38 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.026s · 65.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.9s · import 0.972s · 66MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlowSpec
✓ from metaflow import FlowSpec
The base class for defining a Metaflow workflow.
step
✓ from metaflow import step
A decorator to mark a method as a step in the workflow DAG.
Parameter
✓ from metaflow import Parameter
Used to define command-line parameters for a flow.
card
✓ from metaflow import card
Decorator for creating rich UI cards for steps.
pypi
✓ from metaflow import pypi
Decorator for managing step-specific PyPI dependencies for local and remote execution.
conda
✓ from metaflow import conda
Decorator for managing step-specific Conda dependencies for local and remote execution.
This quickstart defines a basic Metaflow workflow. It consists of three sequential steps: `start`, `hello`, and `end`. The `start` step initializes a message, the `hello` step prints it, and the `end` step marks the completion of the flow. To run this, save it as a Python file (e.g., `hello_flow.py`) and execute `python hello_flow.py run` in your terminal.
import os
from metaflow import FlowSpec, step
class HelloFlow(FlowSpec):
"""A simple Metaflow that prints 'Hi'."""
@step
def start(self):
"""This is the 'start' step. All flows must have a step named 'start'."""
print("HelloFlow is starting.")
self.message = "Metaflow says: Hi!"
self.next(self.hello)
@step
def hello(self):
"""A step for Metaflow to introduce itself."""
print(self.message)
self.next(self.end)
@step
def end(self):
"""This is the 'end' step. All flows must have an 'end' step."""
print("HelloFlow is all done.")
if __name__ == "__main__":
HelloFlow()
metaflow --version
Debug
Known issues
breakingWhile Metaflow generally prioritizes backward compatibility, minor breaking changes can occur, especially in patch versions addressing bug fixes or internal architectural improvements. Always review the GitHub release notes before upgrading.fixConsult the `Release Notes` section on the Metaflow documentation or GitHub releases page for specific breaking changes and migration steps before upgrading.
affects: All versions (check release notes for specifics)
gotchaWhen 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. You must explicitly declare these dependencies using the `@pypi` or `@conda` decorators on your flow or individual steps to ensure reproducibility and correct execution in remote environments.fixUse `@pypi(packages={'package_name': 'version'})` or `@conda(packages={'package_name': 'version'})` decorators on your `FlowSpec` class or individual `@step` methods for all external Python dependencies. affects: All versions when using remote execution.
gotchaMetaflow's most mature and battle-tested integrations are with Amazon Web Services (AWS), including S3 for storage, Batch for compute, and Step Functions for orchestration. While it supports other cloud providers like Azure and GCP, the level of integration and available features may vary, potentially requiring more manual configuration.fixReview Metaflow's documentation for specific cloud provider integrations to understand the scope of support and any necessary configurations for non-AWS environments.
affects: All versions when using non-AWS cloud providers.
gotchaMetaflow 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, as it relies on a *nix-like environment.fixInstall and configure Windows Subsystem for Linux (WSL) and then install Metaflow within the WSL environment.
affects: All versions on Windows.
gotchaData artifacts (instance variables prefixed with `self.`) are automatically persisted and passed between steps. Directly relying on global variables or modifying external state outside of Metaflow's artifact management can lead to non-reproducible runs, especially in distributed or resumed executions, as these changes might not be tracked or correctly restored.fixAlways pass data between steps by assigning it to instance variables (e.g., `self.data_artifact = value`). Avoid relying on global state or external files for inter-step communication, as Metaflow handles serialization and deserialization of `self.` attributes automatically.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fcntl'
The `fcntl` module is Unix-specific and is not available on Windows operating systems, preventing Metaflow from running natively on Windows.
fixMetaflow does not natively support Windows. To run Metaflow on Windows, use Windows Subsystem for Linux (WSL 2) and install Metaflow within the Linux environment.
python: can't open file '/app/metaflow/my_flow.py': [Errno 2] No such file or directory
This error occurs when Metaflow's code packaging silently excludes user code files if any ancestor directory in the flow's absolute path starts with a hidden dot (e.g., `.venv`, `.gitworktrees`), causing remote runs (like Kubernetes or AWS Batch) to fail to find the flow script.
fixEnsure that your Metaflow flow file and its parent directories are not located within any hidden directories (directories starting with a dot). Move your project to a path without hidden ancestor directories.
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: /flows/HelloFlow (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x...>: Failed to establish a new connection: [Errno 61] Connection refused'))
This typically happens when Metaflow is configured to use a local metadata service (e.g., via `METAFLOW_DEFAULT_METADATA='service'` and `METAFLOW_SERVICE_URL='http://localhost:8080/'`) but the Metaflow metadata service is not running or is inaccessible on the specified port.
fixIf you only intend to run Metaflow locally without a dedicated metadata service, set `METAFLOW_DEFAULT_METADATA='local'` in your configuration. If you require a metadata service, ensure it is properly started and accessible at the configured URL and port.
Waiting for lock file /path/to/.conda_lock to be removed...
Metaflow hangs because it's waiting for a Conda lock file to be released, which can happen if a previous environment creation or update process failed or was interrupted, leaving a stale lock file.
fixManually remove the stale lock file specified in the error message (e.g., `/path/to/.conda_lock`) or wait for the `METAFLOW_CONDA_LOCK_TIMEOUT` to expire (default is 3600 seconds).
Could not resolve environment: conflicts found
This error occurs when Metaflow's dependency management (Conda or PyPI decorators) encounters conflicting package versions or incompatible dependencies during environment resolution, making it impossible to create a stable environment for the step.
fixLoosen version constraints on your declared packages in `@conda` or `@pypi` decorators, try different package channels, or ensure all packages are available as wheels (for cross-architecture scenarios) to help the resolver find a compatible set of dependencies.
Upgrade
Version history
2.19.38latest on PyPI · released Aug 18, 2026
Audit
Dependencies
boto3optionalUsed for integrations with AWS services like S3, Batch, and Step Functions. Metaflow is tightly integrated with AWS.
kubernetesoptionalRequired for Kubernetes and Argo Workflows orchestration.
condaoptionalUsed for managing Python environments and dependencies via the @conda decorator.
uvoptionalAn increasingly popular package manager supported by Metaflow (new in 2.15.8) for managing PyPI dependencies.