Install & Compatibility
Where this runs
tested against v0.2.10 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
checkpoint
✓ from metaflow_extensions import checkpoint
✗ from metaflow_extensions import checkpoint
This quickstart demonstrates a Metaflow flow using the `@checkpoint` decorator. The `start` step simulates a long-running, flaky process that increments a counter. It saves the counter value to `current.checkpoint.directory` and calls `current.checkpoint.save()` periodically. Upon restart (due to `@retry` or `resume` command), it loads the last saved counter using `current.checkpoint.is_loaded` and `current.checkpoint.directory`. The `load_policy='eager'` allows checkpoints to be reused across different runs, aiding iterative development. Run with `python your_flow.py run` and try `python your_flow.py resume start` after an interruption.
import os
import random
from metaflow import FlowSpec, step, current, checkpoint, retry
class CheckpointCounterFlow(FlowSpec):
@retry(times=2, minutes_between_retries=1)
@checkpoint(load_policy='eager') # Use 'eager' for development across runs
@step
def start(self):
self.counter = 0
if current.checkpoint.is_loaded:
print(f"Resuming from checkpoint. Counter was {self.counter}")
with open(os.path.join(current.checkpoint.directory, 'counter'), 'r') as f:
self.counter = int(f.read())
print(f"Successfully loaded counter: {self.counter}")
else:
print("Starting from scratch.")
for i in range(5):
self.counter += 1
print(f"Processing iteration {i+1}, counter is {self.counter}")
# Save progress periodically
with open(os.path.join(current.checkpoint.directory, 'counter'), 'w') as f:
f.write(str(self.counter))
current.checkpoint.save()
# Simulate a flaky operation
if random.random() < 0.3:
raise Exception("Simulated failure!")
self.next(self.end)
@step
def end(self):
print(f"Flow finished. Final counter value: {self.counter}")
if __name__ == '__main__':
CheckpointCounterFlow()
Debug
Known issues
breakingThe `metaflow-checkpoint` library is explicitly labeled as EXPERIMENTAL. Its APIs may change in future versions, and it does not offer the same backwards compatibility guarantees as core Metaflow APIs.fixAlways review the latest Metaflow documentation and `metaflow-checkpoint` release notes when upgrading to new versions. Be prepared for potential code adjustments.
affects: 0.2.x and earlier
gotchaThe default `load_policy='fresh'` for `@checkpoint` only loads task-specific checkpoints for retries within the same run. It explicitly disregards existing checkpoints when a *new* run is initiated.fixFor iterative development and resuming across different runs (e.g., stopping a flow and restarting later), use `@checkpoint(load_policy='eager')`. For custom loading logic, use `@checkpoint(load_policy=None)` and manually call `current.checkpoint.load()`.
affects: All versions
gotchaFiles saved to `current.checkpoint.directory` can accumulate across invocations if not managed, potentially leading to performance degradation over time as `current.checkpoint.save()` processes more data.fixEnsure that your checkpointing logic overwrites existing files within `current.checkpoint.directory` or explicitly cleans up the directory between checkpoint saves to prevent excessive file accumulation. For example, always use the same filename for your latest model state.
affects: All versions
Upgrade
Version history
0.2.10latest on PyPI · released Dec 22, 2025
Audit
Dependencies
metaflowrequiredmetaflow-checkpoint is an extension for the Metaflow framework.