prefect.toml

The URL of the Prefect API. If not set, the client will attempt to infer it.

The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret.

The API key used for authentication with the Prefect API. Should be kept secret.

If True, disables SSL checking to allow insecure requests. Setting to False is recommended only during development. For example, when using self-signed certificates.

This configuration settings option specifies the path to an SSL certificate file.

If true, enable support for HTTP/2 for communicating with an API. If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.

The default timeout for requests to the API

If True, use colors in CLI output. If False, output will not include colors codes.

If True, use interactive prompts in CLI commands. If False, no interactive prompts will be used. If None, the value will be dynamically determined based on the presence of an interactive-enabled terminal.

If True, wrap text by inserting new lines in long lines in CLI output. If False, output will not be wrapped.

Whether or not to enable Prometheus metrics in the client.

The port to expose the client Prometheus metrics on.

    The maximum number of retries to perform on failed HTTP requests.
    Defaults to 5. Set to 0 to disable retries.
    See `PREFECT_CLIENT_RETRY_EXTRA_CODES` for details on which HTTP status codes are
    retried.

    A value greater than or equal to zero to control the amount of jitter added to retried
    client requests. Higher values introduce larger amounts of jitter.
    Set to 0 to disable jitter. See `clamped_poisson_interval` for details on the how jitter
    can affect retry lengths.

    A list of extra HTTP status codes to retry on. Defaults to an empty list.
    429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
    may result in unexpected behavior.

    Determines if CSRF token handling is active in the Prefect client for API
    requests.

    When enabled (`True`), the client automatically manages CSRF tokens by
    retrieving, storing, and including them in applicable state-changing requests

    Custom HTTP headers to include with every API request to the Prefect server.
    Headers are specified as key-value pairs. Note that headers like 'User-Agent'
    and CSRF-related headers are managed by Prefect and cannot be overridden.

    Whether the client should check the server's API version on startup.
    When disabled, the client will skip the call to /admin/version that
    normally runs once per client context entry.  This is useful for worker
    subprocesses that inherit a known-compatible server configuration and
    do not need to repeat the version handshake.

Settings for controlling metrics reporting from the client

API URL for Prefect Cloud. Used for authentication with Prefect Cloud.

Whether or not to enable orchestration telemetry.

Maximum size in characters for a single log when sending logs to Prefect Cloud.

The URL of the Prefect Cloud UI. If not set, the client will attempt to infer it.

The default work pool to use when creating deployments.

The default Docker namespace to use when building images.

    Maximum number of events that can be queued for delivery to the
    Prefect server. When the queue is full, new events are dropped with
    a warning. Set to 0 for unbounded (the default).

    Warning: setting this value too low may result in data loss as events
    will be silently dropped when the queue is full.

If True, warn on usage of experimental features.

Settings for configuring the experimental plugin system

Number of seconds between flow run heartbeats. Heartbeats are used to detect crashed flow runs.

This value sets the default number of retries for all flows.

This value sets the default retry delay seconds for all flows.

The default logging level for Prefect's internal machinery loggers.

The default logging level for Prefect loggers.

A path to a logging configuration file. Defaults to $PREFECT_HOME/logging.yml

Additional loggers to attach to Prefect logging at runtime.

If True, print statements in flows and tasks will be redirected to the Prefect logger for the given run.

If True, use colors in CLI output. If False, output will not include colors codes.

    Whether to interpret strings wrapped in square brackets as a style.
    This allows styles to be conveniently added to log messages, e.g.
    `[red]This is a red message.[/red]`. However, the downside is, if enabled,
    strings that contain square brackets may be inaccurately interpreted and
    lead to incomplete output, e.g.
    `[red]This is a red message.[/red]` may be interpreted as
    `[red]This is a red message.[/red]`.

Settings for controlling logging to the API

If True, logs will be sent to the API.

The number of seconds between batched writes of logs to the API.

The number of logs to batch before sending to the API.

The maximum size in characters for a single log. When connected to Prefect Cloud, this value is capped at PREFECT_CLOUD_MAX_LOG_SIZE (default 25,000).

    Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.
    
    All logs sent to the API must be associated with a flow run. The API log handler can
    only be used outside of a flow by manually providing a flow run identifier. Logs
    that are not associated with a flow run will not be sent to the API. This setting can
    be used to determine if a warning or error is displayed when the identifier is missing.

    The following options are available:

    - "warn": Log a warning message.
    - "error": Raise an error.
    - "ignore": Do not log a warning message or raise an error.

Enable the experimental plugin system.

Comma-separated list of plugin names to allow. If set, only these plugins will be loaded.

Comma-separated list of plugin names to deny. These plugins will not be loaded.

Maximum time in seconds for all plugins to complete their setup hooks.

If True, exit if a required plugin fails during setup.

If True, load plugins but do not execute their hooks. Useful for testing.

The default serializer to use when not otherwise specified.

The default setting for persisting results when not otherwise specified.

The block-type/block-document slug of a block to use as the default result storage.

The default location for locally persisted results. Defaults to $PREFECT_HOME/storage.

Whether or not to enable the runner's webserver.

The host address the runner's webserver should bind to.

The port the runner's webserver should bind to.

The log level of the runner's webserver.

Number of missed polls before a runner is considered unhealthy by its webserver.

Maximum number of processes a runner will execute in parallel.

Number of seconds a runner should wait between queries for scheduled work.

Whether to crash flow runs and shut down the runner when cancellation observing fails. When enabled, if both websocket and polling mechanisms for detecting cancellation events fail, all in-flight flow runs will be marked as crashed and the runner will shut down. When disabled (default), the runner will log an error but continue executing flow runs.

Settings for controlling runner server behavior

Controls the application_name field for connections opened from the connection pool when using a PostgreSQL database with the Prefect backend.

PostgreSQL schema name to set in search_path when using a PostgreSQL database with the Prefect backend. Note: The public schema should be included in the search path (e.g. 'myschema, public') to ensure that pg_trgm and other extensions remain available.

Controls statement cache size for PostgreSQL connections. Setting this to 0 is required when using PgBouncer in transaction mode. Defaults to None.

Controls the size of the statement cache for PostgreSQL connections. When set to 0, statement caching is disabled. Defaults to None to use SQLAlchemy's default behavior.

Settings for controlling SQLAlchemy mTLS context when using a PostgreSQL database.

Settings for controlling SQLAlchemy connection behavior; note that these settings only take effect when using a PostgreSQL database.

Controls connection pool size of database connection pools from the Prefect backend.

This setting causes the pool to recycle connections after the given number of seconds has passed; set it to -1 to avoid recycling entirely.

Number of seconds to wait before giving up on getting a connection from the pool. Defaults to 30 seconds.

Controls maximum overflow of the connection pool. To prevent overflow, set to -1.

Controls whether connected to mTLS enabled PostgreSQL when using a PostgreSQL database with the Prefect backend.

This configuration settings option specifies the path to PostgreSQL client certificate authority file.

This configuration settings option specifies the path to PostgreSQL client certificate file.

This configuration settings option specifies the path to PostgreSQL client key file.

This configuration settings option specifies whether to verify PostgreSQL server hostname.

A string to use for basic authentication with the API in the form 'user:password'.

The API's host address (defaults to 127.0.0.1).

The API's port address (defaults to 4200).

The base URL path to serve the API under.

The default limit applied to queries that can return multiple objects, such as POST /flow_runs/filter.

    The API's keep alive timeout (defaults to `5`).
    Refer to <https://www.uvicorn.org/settings/#timeouts> for details.

    When the API is hosted behind a load balancer, you may want to set this to a value
    greater than the load balancer's idle timeout.

    Note this setting only applies when calling `prefect server start`; if hosting the
    API with another tool you will need to configure this there instead.

    Controls the activation of CSRF protection for the Prefect server API.

    When enabled (`True`), the server enforces CSRF validation checks on incoming
    state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF
    token to be included in the request headers or body. This adds a layer of
    security by preventing unauthorized or malicious sites from making requests on
    behalf of authenticated users.

    It is recommended to enable this setting in production environments where the
    API is exposed to web clients to safeguard against CSRF attacks.

    Note: Enabling this setting requires corresponding support in the client for
    CSRF token management. See PREFECT_CLIENT_CSRF_SUPPORT_ENABLED for more.

    Specifies the duration for which a CSRF token remains valid after being issued
    by the server.

    The default expiration time is set to 1 hour, which offers a reasonable
    compromise. Adjust this setting based on your specific security requirements
    and usage patterns.

    A comma-separated list of origins that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all origins.

    A comma-separated list of methods that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all methods.

    A comma-separated list of headers that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all headers.

The maximum size of parameters (in bytes, JSON-serialized) that can be stored on a flow run or deployment. Set to 0 to disable the limit.

The module to use for storing concurrency limit leases.

Initial duration for deployment concurrency lease in seconds.

The maximum number of seconds to wait before retrying when a concurrency slot cannot be acquired.

Settings for controlling SQLAlchemy behavior; note that these settings only take effect when using a PostgreSQL database.

    A database connection URL in a SQLAlchemy-compatible
    format. Prefect currently supports SQLite and Postgres. Note that all
    Prefect database engines must use an async driver - for SQLite, use
    `sqlite+aiosqlite` and for Postgres use `postgresql+asyncpg`.

    SQLite in-memory databases can be used by providing the url
    `sqlite+aiosqlite:///file::memory:?cache=shared&uri=true&check_same_thread=false`,
    which will allow the database to be accessed by multiple threads. Note
    that in-memory databases can not be accessed from multiple processes and
    should only be used for simple tests.

The database driver to use when connecting to the database. If not set, the driver will be inferred from the connection URL.

The database server host.

The database server port.

The user to use when connecting to the database.

The name of the Prefect database on the remote server, or the path to the database file for SQLite.

The password to use when connecting to the database. Should be kept secret.

If True, SQLAlchemy will log all SQL issued to the database. Defaults to False.

If True, the database will be migrated on application startup.

A statement timeout, in seconds, applied to all database interactions made by the Prefect backend. Defaults to 10 seconds.

A connection timeout, in seconds, applied to database connections. Defaults to 5.

The number of seconds to wait before retrying when a deployment flow run cannot secure a concurrency slot from the server.

The name of the Docket instance.

The URL of the Redis server to use for Docket.

    Controls whether or not a subprocess server can be started when no API URL is provided.

    The number of seconds to wait for the server to start when ephemeral mode is enabled.
    Defaults to `20`.

Whether or not to stream events out to the API via websockets.

The number of seconds to cache related resources for in the API.

The maximum number of labels a resource may have.

The maximum number of related resources an Event may have.

The maximum size of an Event when serialized to JSON

The amount of time to retain expired automation buckets

How frequently proactive automations are evaluated

The amount of time to retain events in the database.

The maximum range to look back for backfilling events for a websocket subscriber.

The page size for the queries to backfill events for websocket subscribers.

Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.

Which cache implementation to use for the events system. Should point to a module that exports a Cache class.

Which causal ordering implementation to use for the events system. Should point to a module that exports a CausalOrdering class.

The maximum length of an event name.

The maximum size of a flow run graph on the v2 API

The maximum number of artifacts to show on a flow run graph on the v2 API

Whether or not to stream logs out to the API via websockets.

Whether or not to publish logs to the streaming system.

Whether or not to start the cancellation cleanup service in the server application.

The cancellation cleanup service will look for non-terminal tasks and subflows this often. Defaults to 20.

Comma-separated set of vacuum types to enable. Valid values: 'events', 'flow_runs'. Defaults to 'events'. For backward compatibility, 'true' maps to 'events,flow_runs' and 'false' maps to 'events'. Event vacuum also requires event_persister.enabled (the default).

The database vacuum service will run this often, in seconds. Defaults to 3600 (1 hour).

How old a flow run must be (based on end_time) before it is eligible for deletion. Accepts seconds. Minimum 1 hour. Defaults to 90 days.

The number of records to delete per database transaction. Defaults to 200.

Per-event-type retention period overrides. Keys are event type strings (e.g. 'prefect.flow-run.heartbeat'), values are retention periods in seconds. Event types not listed fall back to server.events.retention_period. Each override is capped by the global events retention period.

Whether or not to start the event logger service in the server application.

Whether or not to start the event persister service in the server application.

The number of events the event persister will attempt to insert in one batch.

The number of events the event persister will attempt to read from the message broker in one batch.

The maximum number of seconds between flushes of the event persister.

The maximum number of events that can be queued in memory for persistence. When the queue is full, new events will be dropped.

The maximum number of consecutive flush failures before events are dropped instead of being re-queued.

Whether or not to start the foreman service in the server application.

The foreman service will check for offline workers this often. Defaults to 15.

    The number of heartbeats that must be missed before a worker is marked as offline. Defaults to `3`.

    The number of seconds to use for online/offline evaluation if a worker's heartbeat
    interval is not set. Defaults to `30`.

    The number of seconds before a deployment is marked as not ready if it has not been
    polled. Defaults to `60`.

    The number of seconds before a work queue is marked as not ready if it has not been
    polled. Defaults to `60`.

Whether or not to start the late runs service in the server application.

    The late runs service will look for runs to mark as late this often. Defaults to `5`.

    The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to `5` seconds.

    Whether or not to start the paused flow run expiration service in the server
    application. If disabled, paused flows that have timed out will remain in a Paused state
    until a resume attempt.

    The pause expiration service will look for runs to mark as failed this often. Defaults to `5`.

Whether or not to start the repossessor service in the server application.

The repossessor service will look for expired leases this often. Defaults to 15.

Whether or not to start the scheduler service in the server application.

    The scheduler loop interval, in seconds. This determines
    how often the scheduler will attempt to schedule new flow runs, but has no
    impact on how quickly either flow runs or task runs are actually executed.
    Defaults to `60`.

    The number of deployments the scheduler will attempt to
    schedule in a single batch. If there are more deployments than the batch
    size, the scheduler immediately attempts to schedule the next batch; it
    does not sleep for `scheduler_loop_seconds` until it has visited every
    deployment once. Defaults to `100`.

    The scheduler will attempt to schedule up to this many
    auto-scheduled runs in the future. Note that runs may have fewer than
    this many scheduled runs, depending on the value of
    `scheduler_max_scheduled_time`.  Defaults to `100`.

    The scheduler will attempt to schedule at least this many
    auto-scheduled runs in the future. Note that runs may have more than
    this many scheduled runs, depending on the value of
    `scheduler_min_scheduled_time`.  Defaults to `3`.

    The scheduler will create new runs up to this far in the
    future. Note that this setting will take precedence over
    `scheduler_max_runs`: if a flow runs once a month and
    `scheduler_max_scheduled_time` is three months, then only three runs will be
    scheduled. Defaults to 100 days (`8640000` seconds).

    The scheduler will create new runs at least this far in the
    future. Note that this setting will take precedence over `scheduler_min_runs`:
    if a flow runs every hour and `scheduler_min_scheduled_time` is three hours,
    then three runs will be scheduled even if `scheduler_min_runs` is 1. Defaults to

    The number of runs the scheduler will attempt to insert in a single batch.
    Defaults to `500`.

    The number of seconds the recent deployments scheduler will wait between checking for recently updated deployments. Defaults to `5`.

Settings for controlling the cancellation cleanup service

Settings for controlling the database vacuum service

Settings for controlling the event persister service

Settings for controlling the event logger service

Settings for controlling the foreman service

Settings for controlling the late runs service

Settings for controlling the scheduler service

Settings for controlling the pause expiration service

Settings for controlling the repossessor service

Settings for controlling the task run recorder service

Settings for controlling the triggers service

Whether or not to start the task run recorder service in the server application.

The number of task runs the task run recorder will attempt to read from the message broker in one batch.

The number of task runs the task run recorder will attempt to insert in one batch.

The maximum number of seconds between flushes of the task run recorder.

Whether or not to start the triggers service in the server application.

The number of events the triggers service will attempt to read from the message broker in one batch.

    The number of seconds to wait before reconnecting to the PostgreSQL NOTIFY/LISTEN 
    connection after an error. Only used when using PostgreSQL as the database.
    Defaults to `10`.

    The number of seconds between heartbeat checks for the PostgreSQL NOTIFY/LISTEN 
    connection to ensure it's still alive. Only used when using PostgreSQL as the database.
    Defaults to `5`.

The default logging level for the Prefect API server.

    When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
    on server startup to help us improve our product.

Whether or not to enable Prometheus metrics in the API.

If True, log retryable errors in the API and it's services.

If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.

Controls whether or not block auto-registration on start

Path to the memo store file. Defaults to $PREFECT_HOME/memo_store.toml

The maximum number of scheduled runs to create for a deployment.

Settings for controlling API server behavior

Settings for controlling server database behavior

Settings for controlling Docket behavior

Settings for controlling ephemeral server behavior

Settings for controlling behavior of the events subsystem

Settings for controlling behavior of the flow run graph

Settings for controlling behavior of the logs subsystem

Settings for controlling server services

Settings for controlling server-side behavior related to tasks

The maximum number of scheduled tasks to queue for submission.

The maximum number of retries to queue for submission.

How long before a PENDING task are made available to another task worker.

The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.

The maximum number of characters allowed for a task run cache key.

Settings for controlling server-side behavior related to task scheduling

Whether or not to serve the Prefect UI.

Whether to serve the experimental V2 UI instead of the default V1 UI.

The connection url for communication from the UI to the API. Defaults to PREFECT_API_URL if set. Otherwise, the default URL is generated from PREFECT_SERVER_API_HOST and PREFECT_SERVER_API_PORT.

The base URL path to serve the Prefect UI from.

The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container).

Whether or not to display promotional content in the UI, including upgrade prompts and marketing banners.

The maximum number of workers for ThreadPoolTaskRunner.

The maximum number of workers for ProcessPoolTaskRunner.

The block-type/block-document slug of a block to use as the default storage for autonomous tasks.

Whether or not to delete failed task submissions from the database.

If True, enables a refresh of cached results: re-executing the task will refresh the cached results.

If True, sets the default cache policy on all tasks to NO_CACHE.

If True, disables caching on all tasks regardless of cache policy.

This value sets the default number of retries for all tasks.

This value sets the default retry delay seconds for all tasks.

If True, results will be persisted by default for all tasks. Set to False to disable persistence by default. Note that setting to False will override the behavior set by a parent flow or task.

Whether to enable OS-level resource metric collection in flow run subprocesses.

Interval in seconds between resource metric collections.

If True, places the API in test mode. This may modify behavior to facilitate testing.

This setting only exists to facilitate unit testing. If True, code is executing in a unit test context. Defaults to False.

If True turns on debug mode for the unit testing event loop.

This setting only exists to facilitate unit testing. If in test mode, this setting will return its value. Otherwise, it returns None.

If True, enables debug mode for the worker only. Unlike PREFECT_DEBUG_MODE, this setting does not propagate to flow runs executed by the worker.

Number of seconds a worker should wait between sending a heartbeat.

Number of seconds a worker should wait between queries for scheduled work.

The number of seconds into the future a worker should query for scheduled work.

Enable worker-side flow run cancellation for pending flow runs. When enabled, the worker will terminate infrastructure for flow runs that are cancelled while still in PENDING state (before the runner starts).

Number of seconds between polls for cancelling flow runs. Used as a fallback when the WebSocket connection for real-time cancellation events is unavailable.

The host address the worker's webserver should bind to.

The port the worker's webserver should bind to.