Great question. Short answer: - If you want an orchestrated flow run (i.e., calling

my_flow()

), Prefect 3.x always needs an API. You can disable the ephemeral API, but then you must point at a running server or the call will error. - If you want to run your flow code purely offline with zero API (no server, no ephemeral), call the underlying Python function with

.fn(...)

. This bypasses orchestration entirely. Options 1) Purely offline (no server, no ephemeral): use .fn

from prefect import flow, task

@task
def add(x, y): 
    return x + y

@flow
def my_flow(x, y):
    return add(x, y)

# No API used at all:
print(my_flow.fn(1, 2))  # 3
print(add.fn(1, 2))      # 3

Notes: - Avoid Prefect-only features (e.g.,

get_run_logger

, retries, caching) when using

.fn

, or temporarily disable the run logger:

from prefect.logging import disable_run_logger
with disable_run_logger():
    my_flow.fn(...)

- This is the recommended pattern for testing and local dev without any API. 2) Prevent Prefect from ever starting an ephemeral API (for normal flow() calls) If you call

my_flow()

and you do not want Prefect to auto-start an ephemeral server, disable it:

# Environment variable (either name works)
export PREFECT_SERVER_EPHEMERAL_ENABLED=false
# or
export PREFECT_SERVER_ALLOW_EPHEMERAL_MODE=false

Or in prefect.toml:

[server.ephemeral]
enabled = false

With ephemeral disabled, calling

my_flow()

without

PREFECT_API_URL

will raise a clear error instead of starting an API. This guarantees no local server is started. If you do want orchestration locally, set

PREFECT_API_URL

to a running server. What’s unavailable without an API (i.e., when using .fn) - No flow/task runs or states - No retries, concurrency limits, caching, deployments, UI, or API-backed logs/metrics Docs - Settings & profiles: Settings and profiles - Settings reference (ServerEphemeralSettings): Settings reference - Testing workflows (using .fn): Test workflows Quick check: Do you want to run your code offline just for local dev/tests (use

.fn

), or do you need a fully orchestrated run but without Cloud (requires a running local server and

PREFECT_API_URL

)?