Settings reference
Reference for all available settings for Prefect.
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
auth_string
The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret.
Type: string | None
Default: None
TOML dotted key path: api.auth_string
Supported environment variables:
PREFECT_API_AUTH_STRING
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
lineage_events_enabled
If True, enables emitting lineage events. Set to False to disable lineage event emission.
Type: boolean
Default: False
TOML dotted key path: experiments.lineage_events_enabled
Supported environment variables:
PREFECT_EXPERIMENTS_LINEAGE_EVENTS_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
heartbeat_frequency
Number of seconds a runner should wait between heartbeats for flow runs.
Type: integer | None
Default: None
TOML dotted key path: runner.heartbeat_frequency
Supported environment variables:
PREFECT_RUNNER_HEARTBEAT_FREQUENCY
server
Type: RunnerServerSettings
TOML dotted key path: runner.server
ServerAPISettings
Settings for controlling API server behavior
auth_string
A string to use for basic authentication with the API; typically in the form ‘user:password’ but can be any string.
Type: string | None
Default: None
TOML dotted key path: server.api.auth_string
Supported environment variables:
PREFECT_SERVER_API_AUTH_STRING
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
related_resource_cache_ttl
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
maximum_related_resources
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: False
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
Was this page helpful?