To use prefect.toml or pyproject.toml for configuration, prefect>=3.1 must be installed.

Root Settings

home

The path to the Prefect home directory. Defaults to ~/.prefect

Type: string

Default: ~/.prefect

TOML dotted key path: home

Supported environment variables: PREFECT_HOME

profiles_path

The path to a profiles configuration file.

Type: string | None

Default: None

TOML dotted key path: profiles_path

Supported environment variables: PREFECT_PROFILES_PATH

debug_mode

If True, enables debug mode which may provide additional logging and debugging features.

Type: boolean

Default: False

TOML dotted key path: debug_mode

Supported environment variables: PREFECT_DEBUG_MODE

api

Type: APISettings

TOML dotted key path: api

cli

Type: CLISettings

TOML dotted key path: cli

client

Type: ClientSettings

TOML dotted key path: client

cloud

Type: CloudSettings

TOML dotted key path: cloud

deployments

Type: DeploymentsSettings

TOML dotted key path: deployments

experiments

Settings for controlling experimental features

Type: ExperimentsSettings

TOML dotted key path: experiments

flows

Type: FlowsSettings

TOML dotted key path: flows

internal

Settings for internal Prefect machinery

Type: InternalSettings

TOML dotted key path: internal

logging

Type: LoggingSettings

TOML dotted key path: logging

results

Type: ResultsSettings

TOML dotted key path: results

runner

Type: RunnerSettings

TOML dotted key path: runner

server

Type: ServerSettings

TOML dotted key path: server

tasks

Settings for controlling task behavior

Type: TasksSettings

TOML dotted key path: tasks

testing

Settings used during testing

Type: TestingSettings

TOML dotted key path: testing

worker

Settings for controlling worker behavior

Type: WorkerSettings

TOML dotted key path: worker

ui_url

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

Type: string | None

Default: None

TOML dotted key path: ui_url

Supported environment variables: PREFECT_UI_URL

silence_api_url_misconfiguration

If True, disable the warning when a user accidentally misconfigure its PREFECT_API_URL Sometimes when a user manually set PREFECT_API_URL to a custom url,reverse-proxy for example, we would like to silence this warning so we will set it to FALSE.

Type: boolean

Default: False

TOML dotted key path: silence_api_url_misconfiguration

Supported environment variables: PREFECT_SILENCE_API_URL_MISCONFIGURATION


APISettings

Settings for interacting with the Prefect API

url

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

Type: string | None

Default: None

TOML dotted key path: api.url

Supported environment variables: PREFECT_API_URL

key

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

Type: string | None

Default: None

TOML dotted key path: api.key

Supported environment variables: PREFECT_API_KEY

tls_insecure_skip_verify

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

Type: boolean

Default: False

TOML dotted key path: api.tls_insecure_skip_verify

Supported environment variables: PREFECT_API_TLS_INSECURE_SKIP_VERIFY

ssl_cert_file

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

Type: string | None

Default: None

TOML dotted key path: api.ssl_cert_file

Supported environment variables: PREFECT_API_SSL_CERT_FILE

enable_http2

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.

Type: boolean

Default: False

TOML dotted key path: api.enable_http2

Supported environment variables: PREFECT_API_ENABLE_HTTP2

request_timeout

The default timeout for requests to the API

Type: number

Default: 60.0

TOML dotted key path: api.request_timeout

Supported environment variables: PREFECT_API_REQUEST_TIMEOUT


CLISettings

Settings for controlling CLI behavior

colors

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

Type: boolean

Default: True

TOML dotted key path: cli.colors

Supported environment variables: PREFECT_CLI_COLORS

prompt

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.

Type: boolean | None

Default: None

TOML dotted key path: cli.prompt

Supported environment variables: PREFECT_CLI_PROMPT

wrap_lines

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

Type: boolean

Default: True

TOML dotted key path: cli.wrap_lines

Supported environment variables: PREFECT_CLI_WRAP_LINES


ClientMetricsSettings

Settings for controlling metrics reporting from the client

enabled

Whether or not to enable Prometheus metrics in the client.

Type: boolean

Default: False

TOML dotted key path: client.metrics.enabled

Supported environment variables: PREFECT_CLIENT_METRICS_ENABLED, PREFECT_CLIENT_ENABLE_METRICS

port

The port to expose the client Prometheus metrics on.

Type: integer

Default: 4201

TOML dotted key path: client.metrics.port

Supported environment variables: PREFECT_CLIENT_METRICS_PORT


ClientSettings

Settings for controlling API client behavior

max_retries

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.

Type: integer

Default: 5

Constraints:

  • Minimum: 0

TOML dotted key path: client.max_retries

Supported environment variables: PREFECT_CLIENT_MAX_RETRIES

retry_jitter_factor

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.

Type: number

Default: 0.2

Constraints:

  • Minimum: 0.0

TOML dotted key path: client.retry_jitter_factor

Supported environment variables: PREFECT_CLIENT_RETRY_JITTER_FACTOR

retry_extra_codes

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.

Type: string | integer | array | None

TOML dotted key path: client.retry_extra_codes

Supported environment variables: PREFECT_CLIENT_RETRY_EXTRA_CODES

csrf_support_enabled

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

Type: boolean

Default: True

TOML dotted key path: client.csrf_support_enabled

Supported environment variables: PREFECT_CLIENT_CSRF_SUPPORT_ENABLED

metrics

Type: ClientMetricsSettings

TOML dotted key path: client.metrics


CloudSettings

Settings for interacting with Prefect Cloud

api_url

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

Type: string

Default: https://api.prefect.cloud/api

TOML dotted key path: cloud.api_url

Supported environment variables: PREFECT_CLOUD_API_URL

ui_url

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

Type: string | None

Default: None

TOML dotted key path: cloud.ui_url

Supported environment variables: PREFECT_CLOUD_UI_URL


DeploymentsSettings

Settings for configuring deployments defaults

default_work_pool_name

The default work pool to use when creating deployments.

Type: string | None

Default: None

TOML dotted key path: deployments.default_work_pool_name

Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME, PREFECT_DEFAULT_WORK_POOL_NAME

default_docker_build_namespace

The default Docker namespace to use when building images.

Type: string | None

Default: None

TOML dotted key path: deployments.default_docker_build_namespace

Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_DOCKER_BUILD_NAMESPACE, PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE


ExperimentsSettings

Settings for configuring experimental features

warn

If True, warn on usage of experimental features.

Type: boolean

Default: True

TOML dotted key path: experiments.warn

Supported environment variables: PREFECT_EXPERIMENTS_WARN, PREFECT_EXPERIMENTAL_WARN

telemetry_enabled

Enables sending telemetry to Prefect Cloud.

Type: boolean

Default: False

TOML dotted key path: experiments.telemetry_enabled

Supported environment variables: PREFECT_EXPERIMENTS_TELEMETRY_ENABLED


FlowsSettings

Settings for controlling flow behavior

default_retries

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

Type: integer

Default: 0

Constraints:

  • Minimum: 0

TOML dotted key path: flows.default_retries

Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRIES, PREFECT_FLOW_DEFAULT_RETRIES

default_retry_delay_seconds

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

Type: integer | number | array

Default: 0

TOML dotted key path: flows.default_retry_delay_seconds

Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS


InternalSettings

logging_level

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

Type: string

Default: ERROR

Constraints:

  • Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: internal.logging_level

Supported environment variables: PREFECT_INTERNAL_LOGGING_LEVEL, PREFECT_LOGGING_INTERNAL_LEVEL


LoggingSettings

Settings for controlling logging behavior

level

The default logging level for Prefect loggers.

Type: string

Default: INFO

Constraints:

  • Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: logging.level

Supported environment variables: PREFECT_LOGGING_LEVEL

config_path

The path to a custom YAML logging configuration file.

Type: string | None

Default: None

TOML dotted key path: logging.config_path

Supported environment variables: PREFECT_LOGGING_CONFIG_PATH, PREFECT_LOGGING_SETTINGS_PATH

extra_loggers

Additional loggers to attach to Prefect logging at runtime.

Type: string | array | None

Default: None

TOML dotted key path: logging.extra_loggers

Supported environment variables: PREFECT_LOGGING_EXTRA_LOGGERS

log_prints

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

Type: boolean

Default: False

TOML dotted key path: logging.log_prints

Supported environment variables: PREFECT_LOGGING_LOG_PRINTS

colors

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

Type: boolean

Default: True

TOML dotted key path: logging.colors

Supported environment variables: PREFECT_LOGGING_COLORS

markup

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].

Type: boolean

Default: False

TOML dotted key path: logging.markup

Supported environment variables: PREFECT_LOGGING_MARKUP

to_api

Type: LoggingToAPISettings

TOML dotted key path: logging.to_api


LoggingToAPISettings

Settings for controlling logging to the API

enabled

If True, logs will be sent to the API.

Type: boolean

Default: True

TOML dotted key path: logging.to_api.enabled

Supported environment variables: PREFECT_LOGGING_TO_API_ENABLED

batch_interval

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

Type: number

Default: 2.0

TOML dotted key path: logging.to_api.batch_interval

Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_INTERVAL

batch_size

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

Type: integer

Default: 4000000

TOML dotted key path: logging.to_api.batch_size

Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_SIZE

max_log_size

The maximum size in bytes for a single log.

Type: integer

Default: 1000000

TOML dotted key path: logging.to_api.max_log_size

Supported environment variables: PREFECT_LOGGING_TO_API_MAX_LOG_SIZE

when_missing_flow

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.

Type: string

Default: warn

Constraints:

  • Allowed values: ‘warn’, ‘error’, ‘ignore’

TOML dotted key path: logging.to_api.when_missing_flow

Supported environment variables: PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW


ResultsSettings

Settings for controlling result storage behavior

default_serializer

The default serializer to use when not otherwise specified.

Type: string

Default: pickle

TOML dotted key path: results.default_serializer

Supported environment variables: PREFECT_RESULTS_DEFAULT_SERIALIZER

persist_by_default

The default setting for persisting results when not otherwise specified.

Type: boolean

Default: False

TOML dotted key path: results.persist_by_default

Supported environment variables: PREFECT_RESULTS_PERSIST_BY_DEFAULT

default_storage_block

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

Type: string | None

Default: None

TOML dotted key path: results.default_storage_block

Supported environment variables: PREFECT_RESULTS_DEFAULT_STORAGE_BLOCK, PREFECT_DEFAULT_RESULT_STORAGE_BLOCK

local_storage_path

The path to a directory to store results in.

Type: string | None

Default: None

TOML dotted key path: results.local_storage_path

Supported environment variables: PREFECT_RESULTS_LOCAL_STORAGE_PATH, PREFECT_LOCAL_STORAGE_PATH


RunnerServerSettings

Settings for controlling runner server behavior

enable

Whether or not to enable the runner’s webserver.

Type: boolean

Default: False

TOML dotted key path: runner.server.enable

Supported environment variables: PREFECT_RUNNER_SERVER_ENABLE

host

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

Type: string

Default: localhost

TOML dotted key path: runner.server.host

Supported environment variables: PREFECT_RUNNER_SERVER_HOST

port

The port the runner’s webserver should bind to.

Type: integer

Default: 8080

TOML dotted key path: runner.server.port

Supported environment variables: PREFECT_RUNNER_SERVER_PORT

log_level

The log level of the runner’s webserver.

Type: string

Default: error

Constraints:

  • Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: runner.server.log_level

Supported environment variables: PREFECT_RUNNER_SERVER_LOG_LEVEL

missed_polls_tolerance

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

Type: integer

Default: 2

TOML dotted key path: runner.server.missed_polls_tolerance

Supported environment variables: PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE


RunnerSettings

Settings for controlling runner behavior

process_limit

Maximum number of processes a runner will execute in parallel.

Type: integer

Default: 5

TOML dotted key path: runner.process_limit

Supported environment variables: PREFECT_RUNNER_PROCESS_LIMIT

poll_frequency

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

Type: integer

Default: 10

TOML dotted key path: runner.poll_frequency

Supported environment variables: PREFECT_RUNNER_POLL_FREQUENCY

server

Type: RunnerServerSettings

TOML dotted key path: runner.server


ServerAPISettings

Settings for controlling API server behavior

host

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

Type: string

Default: 127.0.0.1

TOML dotted key path: server.api.host

Supported environment variables: PREFECT_SERVER_API_HOST

port

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

Type: integer

Default: 4200

TOML dotted key path: server.api.port

Supported environment variables: PREFECT_SERVER_API_PORT

default_limit

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

Type: integer

Default: 200

TOML dotted key path: server.api.default_limit

Supported environment variables: PREFECT_SERVER_API_DEFAULT_LIMIT, PREFECT_API_DEFAULT_LIMIT

keepalive_timeout

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.

Type: integer

Default: 5

TOML dotted key path: server.api.keepalive_timeout

Supported environment variables: PREFECT_SERVER_API_KEEPALIVE_TIMEOUT

csrf_protection_enabled

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.

Type: boolean

Default: False

TOML dotted key path: server.api.csrf_protection_enabled

Supported environment variables: PREFECT_SERVER_API_CSRF_PROTECTION_ENABLED, PREFECT_SERVER_CSRF_PROTECTION_ENABLED

csrf_token_expiration

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.

Type: string

Default: PT1H

TOML dotted key path: server.api.csrf_token_expiration

Supported environment variables: PREFECT_SERVER_API_CSRF_TOKEN_EXPIRATION, PREFECT_SERVER_CSRF_TOKEN_EXPIRATION

cors_allowed_origins

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.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_origins

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS, PREFECT_SERVER_CORS_ALLOWED_ORIGINS

cors_allowed_methods

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.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_methods

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_METHODS, PREFECT_SERVER_CORS_ALLOWED_METHODS

cors_allowed_headers

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.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_headers

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_HEADERS, PREFECT_SERVER_CORS_ALLOWED_HEADERS


ServerDatabaseSettings

Settings for controlling server database behavior

connection_url

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.

Type: string | None

Default: None

TOML dotted key path: server.database.connection_url

Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_URL, PREFECT_API_DATABASE_CONNECTION_URL

driver

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

Type: string | None

Default: None

TOML dotted key path: server.database.driver

Supported environment variables: PREFECT_SERVER_DATABASE_DRIVER, PREFECT_API_DATABASE_DRIVER

host

The database server host.

Type: string | None

Default: None

TOML dotted key path: server.database.host

Supported environment variables: PREFECT_SERVER_DATABASE_HOST, PREFECT_API_DATABASE_HOST

port

The database server port.

Type: integer | None

Default: None

TOML dotted key path: server.database.port

Supported environment variables: PREFECT_SERVER_DATABASE_PORT, PREFECT_API_DATABASE_PORT

user

The user to use when connecting to the database.

Type: string | None

Default: None

TOML dotted key path: server.database.user

Supported environment variables: PREFECT_SERVER_DATABASE_USER, PREFECT_API_DATABASE_USER

name

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

Type: string | None

Default: None

TOML dotted key path: server.database.name

Supported environment variables: PREFECT_SERVER_DATABASE_NAME, PREFECT_API_DATABASE_NAME

password

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

Type: string | None

Default: None

TOML dotted key path: server.database.password

Supported environment variables: PREFECT_SERVER_DATABASE_PASSWORD, PREFECT_API_DATABASE_PASSWORD

echo

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

Type: boolean

Default: False

TOML dotted key path: server.database.echo

Supported environment variables: PREFECT_SERVER_DATABASE_ECHO, PREFECT_API_DATABASE_ECHO

migrate_on_start

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

Type: boolean

Default: True

TOML dotted key path: server.database.migrate_on_start

Supported environment variables: PREFECT_SERVER_DATABASE_MIGRATE_ON_START, PREFECT_API_DATABASE_MIGRATE_ON_START

timeout

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

Type: number | None

Default: 10.0

TOML dotted key path: server.database.timeout

Supported environment variables: PREFECT_SERVER_DATABASE_TIMEOUT, PREFECT_API_DATABASE_TIMEOUT

connection_timeout

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

Type: number | None

Default: 5

TOML dotted key path: server.database.connection_timeout

Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_TIMEOUT, PREFECT_API_DATABASE_CONNECTION_TIMEOUT

sqlalchemy_pool_size

Controls connection pool size when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy pool size will be used.

Type: integer | None

Default: None

TOML dotted key path: server.database.sqlalchemy_pool_size

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_SIZE, PREFECT_SQLALCHEMY_POOL_SIZE

sqlalchemy_max_overflow

Controls maximum overflow of the connection pool when using a PostgreSQL database with the Prefect API. If not set, the default SQLAlchemy maximum overflow value will be used.

Type: integer | None

Default: None

TOML dotted key path: server.database.sqlalchemy_max_overflow

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_MAX_OVERFLOW, PREFECT_SQLALCHEMY_MAX_OVERFLOW


ServerDeploymentsSettings

concurrency_slot_wait_seconds

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

Type: number

Default: 30.0

Constraints:

  • Minimum: 0.0

TOML dotted key path: server.deployments.concurrency_slot_wait_seconds

Supported environment variables: PREFECT_SERVER_DEPLOYMENTS_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_DEPLOYMENT_CONCURRENCY_SLOT_WAIT_SECONDS


ServerEphemeralSettings

Settings for controlling ephemeral server behavior

enabled

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

Type: boolean

Default: False

TOML dotted key path: server.ephemeral.enabled

Supported environment variables: PREFECT_SERVER_EPHEMERAL_ENABLED, PREFECT_SERVER_ALLOW_EPHEMERAL_MODE

startup_timeout_seconds

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

Type: integer

Default: 20

TOML dotted key path: server.ephemeral.startup_timeout_seconds

Supported environment variables: PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS


ServerEventsSettings

Settings for controlling behavior of the events subsystem

stream_out_enabled

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

Type: boolean

Default: True

TOML dotted key path: server.events.stream_out_enabled

Supported environment variables: PREFECT_SERVER_EVENTS_STREAM_OUT_ENABLED, PREFECT_API_EVENTS_STREAM_OUT_ENABLED

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

Type: string

Default: PT5M

TOML dotted key path: server.events.related_resource_cache_ttl

Supported environment variables: PREFECT_SERVER_EVENTS_RELATED_RESOURCE_CACHE_TTL, PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL

maximum_labels_per_resource

The maximum number of labels a resource may have.

Type: integer

Default: 500

TOML dotted key path: server.events.maximum_labels_per_resource

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_LABELS_PER_RESOURCE, PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE

The maximum number of related resources an Event may have.

Type: integer

Default: 500

TOML dotted key path: server.events.maximum_related_resources

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_RELATED_RESOURCES, PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES

maximum_size_bytes

The maximum size of an Event when serialized to JSON

Type: integer

Default: 1500000

TOML dotted key path: server.events.maximum_size_bytes

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_SIZE_BYTES, PREFECT_EVENTS_MAXIMUM_SIZE_BYTES

expired_bucket_buffer

The amount of time to retain expired automation buckets

Type: string

Default: PT1M

TOML dotted key path: server.events.expired_bucket_buffer

Supported environment variables: PREFECT_SERVER_EVENTS_EXPIRED_BUCKET_BUFFER, PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER

proactive_granularity

How frequently proactive automations are evaluated

Type: string

Default: PT5S

TOML dotted key path: server.events.proactive_granularity

Supported environment variables: PREFECT_SERVER_EVENTS_PROACTIVE_GRANULARITY, PREFECT_EVENTS_PROACTIVE_GRANULARITY

retention_period

The amount of time to retain events in the database.

Type: string

Default: P7D

TOML dotted key path: server.events.retention_period

Supported environment variables: PREFECT_SERVER_EVENTS_RETENTION_PERIOD, PREFECT_EVENTS_RETENTION_PERIOD

maximum_websocket_backfill

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

Type: string

Default: PT15M

TOML dotted key path: server.events.maximum_websocket_backfill

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL, PREFECT_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL

websocket_backfill_page_size

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

Type: integer

Default: 250

TOML dotted key path: server.events.websocket_backfill_page_size

Supported environment variables: PREFECT_SERVER_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE, PREFECT_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE

messaging_broker

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

Type: string

Default: prefect.server.utilities.messaging.memory

TOML dotted key path: server.events.messaging_broker

Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_BROKER, PREFECT_MESSAGING_BROKER

messaging_cache

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

Type: string

Default: prefect.server.utilities.messaging.memory

TOML dotted key path: server.events.messaging_cache

Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_CACHE, PREFECT_MESSAGING_CACHE

maximum_event_name_length

The maximum length of an event name.

Type: integer

Default: 1024

TOML dotted key path: server.events.maximum_event_name_length

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_EVENT_NAME_LENGTH


ServerFlowRunGraphSettings

Settings for controlling behavior of the flow run graph

max_nodes

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

Type: integer

Default: 10000

TOML dotted key path: server.flow_run_graph.max_nodes

Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_NODES, PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES

max_artifacts

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

Type: integer

Default: 10000

TOML dotted key path: server.flow_run_graph.max_artifacts

Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_ARTIFACTS, PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS


ServerServicesCancellationCleanupSettings

Settings for controlling the cancellation cleanup service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.cancellation_cleanup.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_ENABLED, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED

loop_seconds

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

Type: number

Default: 20

TOML dotted key path: server.services.cancellation_cleanup.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS


ServerServicesEventPersisterSettings

Settings for controlling the event persister service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.event_persister.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_ENABLED, PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED

batch_size

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

Type: integer

Default: 20

TOML dotted key path: server.services.event_persister.batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE, PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE

flush_interval

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

Type: number

Default: 5

TOML dotted key path: server.services.event_persister.flush_interval

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL, PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL


ServerServicesFlowRunNotificationsSettings

Settings for controlling the flow run notifications service

enabled

Whether or not to start the flow run notifications service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.flow_run_notifications.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED, PREFECT_API_SERVICES_FLOW_RUN_NOTIFICATIONS_ENABLED


ServerServicesForemanSettings

Settings for controlling the foreman service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.foreman.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_ENABLED, PREFECT_API_SERVICES_FOREMAN_ENABLED

loop_seconds

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

Type: number

Default: 15

TOML dotted key path: server.services.foreman.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_LOOP_SECONDS, PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS

inactivity_heartbeat_multiple

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

Type: integer

Default: 3

TOML dotted key path: server.services.foreman.inactivity_heartbeat_multiple

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE, PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE

fallback_heartbeat_interval_seconds

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

Type: integer

Default: 30

TOML dotted key path: server.services.foreman.fallback_heartbeat_interval_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS, PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS

deployment_last_polled_timeout_seconds

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

Type: integer

Default: 60

TOML dotted key path: server.services.foreman.deployment_last_polled_timeout_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS

work_queue_last_polled_timeout_seconds

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

Type: integer

Default: 60

TOML dotted key path: server.services.foreman.work_queue_last_polled_timeout_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS


ServerServicesLateRunsSettings

Settings for controlling the late runs service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.late_runs.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_ENABLED, PREFECT_API_SERVICES_LATE_RUNS_ENABLED

loop_seconds

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

Type: number

Default: 5

TOML dotted key path: server.services.late_runs.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_LOOP_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS

after_seconds

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.

Type: string

Default: PT15S

TOML dotted key path: server.services.late_runs.after_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_AFTER_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS


ServerServicesPauseExpirationsSettings

Settings for controlling the pause expiration service

enabled

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.

Type: boolean

Default: True

TOML dotted key path: server.services.pause_expirations.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_ENABLED, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED

loop_seconds

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

Type: number

Default: 5

TOML dotted key path: server.services.pause_expirations.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS


ServerServicesSchedulerSettings

Settings for controlling the scheduler service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.scheduler.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_ENABLED, PREFECT_API_SERVICES_SCHEDULER_ENABLED

loop_seconds

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.

Type: number

Default: 60

TOML dotted key path: server.services.scheduler.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_LOOP_SECONDS, PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS

deployment_batch_size

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.

Type: integer

Default: 100

TOML dotted key path: server.services.scheduler.deployment_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE

max_runs

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.

Type: integer

Default: 100

TOML dotted key path: server.services.scheduler.max_runs

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS, PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS

min_runs

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.

Type: integer

Default: 3

TOML dotted key path: server.services.scheduler.min_runs

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS, PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS

max_scheduled_time

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).

Type: string

Default: P100D

TOML dotted key path: server.services.scheduler.max_scheduled_time

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME

min_scheduled_time

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

Type: string

Default: PT1H

TOML dotted key path: server.services.scheduler.min_scheduled_time

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME

insert_batch_size

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

Type: integer

Default: 500

TOML dotted key path: server.services.scheduler.insert_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_INSERT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE


ServerServicesSettings

Settings for controlling server services

cancellation_cleanup

Type: ServerServicesCancellationCleanupSettings

TOML dotted key path: server.services.cancellation_cleanup

event_persister

Type: ServerServicesEventPersisterSettings

TOML dotted key path: server.services.event_persister

flow_run_notifications

Type: ServerServicesFlowRunNotificationsSettings

TOML dotted key path: server.services.flow_run_notifications

foreman

Type: ServerServicesForemanSettings

TOML dotted key path: server.services.foreman

late_runs

Type: ServerServicesLateRunsSettings

TOML dotted key path: server.services.late_runs

scheduler

Type: ServerServicesSchedulerSettings

TOML dotted key path: server.services.scheduler

pause_expirations

Type: ServerServicesPauseExpirationsSettings

TOML dotted key path: server.services.pause_expirations

task_run_recorder

Type: ServerServicesTaskRunRecorderSettings

TOML dotted key path: server.services.task_run_recorder

triggers

Type: ServerServicesTriggersSettings

TOML dotted key path: server.services.triggers


ServerServicesTaskRunRecorderSettings

Settings for controlling the task run recorder service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.task_run_recorder.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_ENABLED, PREFECT_API_SERVICES_TASK_RUN_RECORDER_ENABLED


ServerServicesTriggersSettings

Settings for controlling the triggers service

enabled

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

Type: boolean

Default: True

TOML dotted key path: server.services.triggers.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_ENABLED, PREFECT_API_SERVICES_TRIGGERS_ENABLED


ServerSettings

Settings for controlling server behavior

logging_level

The default logging level for the Prefect API server.

Type: string

Default: WARNING

Constraints:

  • Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: server.logging_level

Supported environment variables: PREFECT_SERVER_LOGGING_LEVEL, PREFECT_LOGGING_SERVER_LEVEL

analytics_enabled

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

Type: boolean

Default: True

TOML dotted key path: server.analytics_enabled

Supported environment variables: PREFECT_SERVER_ANALYTICS_ENABLED

metrics_enabled

Whether or not to enable Prometheus metrics in the API.

Type: boolean

Default: False

TOML dotted key path: server.metrics_enabled

Supported environment variables: PREFECT_SERVER_METRICS_ENABLED, PREFECT_API_ENABLE_METRICS

log_retryable_errors

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

Type: boolean

Default: False

TOML dotted key path: server.log_retryable_errors

Supported environment variables: PREFECT_SERVER_LOG_RETRYABLE_ERRORS, PREFECT_API_LOG_RETRYABLE_ERRORS

register_blocks_on_start

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.

Type: boolean

Default: True

TOML dotted key path: server.register_blocks_on_start

Supported environment variables: PREFECT_SERVER_REGISTER_BLOCKS_ON_START, PREFECT_API_BLOCKS_REGISTER_ON_START

memoize_block_auto_registration

Controls whether or not block auto-registration on start

Type: boolean

Default: True

TOML dotted key path: server.memoize_block_auto_registration

Supported environment variables: PREFECT_SERVER_MEMOIZE_BLOCK_AUTO_REGISTRATION, PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION

memo_store_path

The path to the memo store file.

Type: string | None

Default: None

TOML dotted key path: server.memo_store_path

Supported environment variables: PREFECT_SERVER_MEMO_STORE_PATH, PREFECT_MEMO_STORE_PATH

deployment_schedule_max_scheduled_runs

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

Type: integer

Default: 50

TOML dotted key path: server.deployment_schedule_max_scheduled_runs

Supported environment variables: PREFECT_SERVER_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS, PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS

api

Type: ServerAPISettings

TOML dotted key path: server.api

database

Type: ServerDatabaseSettings

TOML dotted key path: server.database

deployments

Settings for controlling server deployments behavior

Type: ServerDeploymentsSettings

TOML dotted key path: server.deployments

ephemeral

Type: ServerEphemeralSettings

TOML dotted key path: server.ephemeral

events

Settings for controlling server events behavior

Type: ServerEventsSettings

TOML dotted key path: server.events

flow_run_graph

Settings for controlling flow run graph behavior

Type: ServerFlowRunGraphSettings

TOML dotted key path: server.flow_run_graph

services

Settings for controlling server services behavior

Type: ServerServicesSettings

TOML dotted key path: server.services

tasks

Settings for controlling server tasks behavior

Type: ServerTasksSettings

TOML dotted key path: server.tasks

ui

Settings for controlling server UI behavior

Type: ServerUISettings

TOML dotted key path: server.ui


ServerTasksSchedulingSettings

Settings for controlling server-side behavior related to task scheduling

max_scheduled_queue_size

The maximum number of scheduled tasks to queue for submission.

Type: integer

Default: 1000

TOML dotted key path: server.tasks.scheduling.max_scheduled_queue_size

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE

max_retry_queue_size

The maximum number of retries to queue for submission.

Type: integer

Default: 100

TOML dotted key path: server.tasks.scheduling.max_retry_queue_size

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_RETRY_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE

pending_task_timeout

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

Type: string

Default: PT0S

TOML dotted key path: server.tasks.scheduling.pending_task_timeout

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_PENDING_TASK_TIMEOUT, PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT


ServerTasksSettings

Settings for controlling server-side behavior related to tasks

tag_concurrency_slot_wait_seconds

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

Type: number

Default: 30

Constraints:

  • Minimum: 0.0

TOML dotted key path: server.tasks.tag_concurrency_slot_wait_seconds

Supported environment variables: PREFECT_SERVER_TASKS_TAG_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS

max_cache_key_length

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

Type: integer

Default: 2000

TOML dotted key path: server.tasks.max_cache_key_length

Supported environment variables: PREFECT_SERVER_TASKS_MAX_CACHE_KEY_LENGTH, PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH

scheduling

Type: ServerTasksSchedulingSettings

TOML dotted key path: server.tasks.scheduling


ServerUISettings

enabled

Whether or not to serve the Prefect UI.

Type: boolean

Default: True

TOML dotted key path: server.ui.enabled

Supported environment variables: PREFECT_SERVER_UI_ENABLED, PREFECT_UI_ENABLED

api_url

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.

Type: string | None

Default: None

TOML dotted key path: server.ui.api_url

Supported environment variables: PREFECT_SERVER_UI_API_URL, PREFECT_UI_API_URL

serve_base

The base URL path to serve the Prefect UI from.

Type: string

Default: /

TOML dotted key path: server.ui.serve_base

Supported environment variables: PREFECT_SERVER_UI_SERVE_BASE, PREFECT_UI_SERVE_BASE

static_directory

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).

Type: string | None

Default: None

TOML dotted key path: server.ui.static_directory

Supported environment variables: PREFECT_SERVER_UI_STATIC_DIRECTORY, PREFECT_UI_STATIC_DIRECTORY


TasksRunnerSettings

thread_pool_max_workers

The maximum number of workers for ThreadPoolTaskRunner.

Type: integer | None

Default: None

TOML dotted key path: tasks.runner.thread_pool_max_workers

Supported environment variables: PREFECT_TASKS_RUNNER_THREAD_POOL_MAX_WORKERS, PREFECT_TASK_RUNNER_THREAD_POOL_MAX_WORKERS


TasksSchedulingSettings

default_storage_block

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

Type: string | None

Default: None

TOML dotted key path: tasks.scheduling.default_storage_block

Supported environment variables: PREFECT_TASKS_SCHEDULING_DEFAULT_STORAGE_BLOCK, PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK

delete_failed_submissions

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

Type: boolean

Default: True

TOML dotted key path: tasks.scheduling.delete_failed_submissions

Supported environment variables: PREFECT_TASKS_SCHEDULING_DELETE_FAILED_SUBMISSIONS, PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS


TasksSettings

refresh_cache

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

Type: boolean

Default: False

TOML dotted key path: tasks.refresh_cache

Supported environment variables: PREFECT_TASKS_REFRESH_CACHE

default_retries

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

Type: integer

Default: 0

Constraints:

  • Minimum: 0

TOML dotted key path: tasks.default_retries

Supported environment variables: PREFECT_TASKS_DEFAULT_RETRIES, PREFECT_TASK_DEFAULT_RETRIES

default_retry_delay_seconds

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

Type: integer | number | array

Default: 0

TOML dotted key path: tasks.default_retry_delay_seconds

Supported environment variables: PREFECT_TASKS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS

default_persist_result

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.

Type: boolean | None

Default: None

TOML dotted key path: tasks.default_persist_result

Supported environment variables: PREFECT_TASKS_DEFAULT_PERSIST_RESULT

runner

Settings for controlling task runner behavior

Type: TasksRunnerSettings

TOML dotted key path: tasks.runner

scheduling

Settings for controlling client-side task scheduling behavior

Type: TasksSchedulingSettings

TOML dotted key path: tasks.scheduling


TestingSettings

test_mode

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

Type: boolean

Default: False

TOML dotted key path: testing.test_mode

Supported environment variables: PREFECT_TESTING_TEST_MODE, PREFECT_TEST_MODE

unit_test_mode

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

Type: boolean

Default: False

TOML dotted key path: testing.unit_test_mode

Supported environment variables: PREFECT_TESTING_UNIT_TEST_MODE, PREFECT_UNIT_TEST_MODE

unit_test_loop_debug

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

Type: boolean

Default: True

TOML dotted key path: testing.unit_test_loop_debug

Supported environment variables: PREFECT_TESTING_UNIT_TEST_LOOP_DEBUG, PREFECT_UNIT_TEST_LOOP_DEBUG

test_setting

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

Type: None

Default: FOO

TOML dotted key path: testing.test_setting

Supported environment variables: PREFECT_TESTING_TEST_SETTING, PREFECT_TEST_SETTING


WorkerSettings

heartbeat_seconds

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

Type: number

Default: 30

TOML dotted key path: worker.heartbeat_seconds

Supported environment variables: PREFECT_WORKER_HEARTBEAT_SECONDS

query_seconds

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

Type: number

Default: 10

TOML dotted key path: worker.query_seconds

Supported environment variables: PREFECT_WORKER_QUERY_SECONDS

prefetch_seconds

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

Type: number

Default: 10

TOML dotted key path: worker.prefetch_seconds

Supported environment variables: PREFECT_WORKER_PREFETCH_SECONDS

webserver

Settings for a worker’s webserver

Type: WorkerWebserverSettings

TOML dotted key path: worker.webserver


WorkerWebserverSettings

host

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

Type: string

Default: 0.0.0.0

TOML dotted key path: worker.webserver.host

Supported environment variables: PREFECT_WORKER_WEBSERVER_HOST

port

The port the worker’s webserver should bind to.

Type: integer

Default: 8080

TOML dotted key path: worker.webserver.port

Supported environment variables: PREFECT_WORKER_WEBSERVER_PORT