Configure settings and profiles

Prefect settings let you customize your workflow environment, including your Cloud and self-hosted server preferences.

Many of Prefect’s features—especially interactions with the API—require configuration. You can configure settings through the following methods:

• Environment Variables: All Prefect settings can be set using environment variables prefixed with PREFECT_. Environment variables are useful for temporarily overriding settings or configuring the runtime environment of a workflow. They take precedence over profile settings, making them ideal for adjustments that should only apply to a single session or process. These can also be set in a .env file, which will be automatically applied when using prefect in that directory.

• Profiles: Prefect profiles store sets of settings locally on your machine. When you activate a profile, its settings are applied, allowing you to switch easily between different configurations. For example, you might use one profile for a self-hosted Prefect server and another for Prefect Cloud.

To view all available settings and their active values from the command line, run:

prefect config view --show-defaults

These settings are type-validated and you may verify your setup at any time with:

prefect config validate

Manage profiles

Prefect profiles are persisted groups of settings on your local machine. By default these settings are stored in a TOML file located at ~/.prefect/profiles.toml. This location can be configured by setting PREFECT_PROFILES_PATH.

One and only one profile can be active at any time.

Immediately after installation, the ephemeral profile will be used, which only has 1 setting configured:

» docker run -it prefecthq/prefect:3-latest
  ___ ___ ___ ___ ___ ___ _____
 | _ \ _ \ __| __| __/ __|_   _|
 |  _/   / _|| _|| _| (__  | |
 |_| |_|_\___|_| |___\___| |_|


root@e56e34ab8934:/opt/prefect $ prefect config view
PREFECT_PROFILE='ephemeral'
PREFECT_SERVER_ALLOW_EPHEMERAL_MODE='True' (from profile)

What is PREFECT_SERVER_ALLOW_EPHEMERAL_MODE?

This setting allows a Prefect server to be run ephemerally as needed without explicitly starting a server process.

The prefect profile CLI commands enable you to create, review, and manage profiles:

Command	Description
create	Create a new profile; use the --from flag to copy settings from another profile.
delete	Delete the given profile.
inspect	Display settings from a given profile; defaults to active.
ls	List all profile names.
rename	Change the name of a profile.
use	Switch the active profile.
populate-defaults	Populate your profiles.toml file with opinionated stock profiles.

… or you may edit your profiles.toml file directly:

vim ~/.prefect/profiles.toml

Configure settings for the active profile

The prefect config CLI commands enable you to manage the settings within the currently active profile.

Command	Description
set	Change the value for a setting.
unset	Restore the default value for a setting.
view	Display the current settings.

For example, the following CLI commands set configuration in the ephemeral profile and then create a new profile with new settings:

prefect profile use ephemeral
prefect config set PREFECT_API_URL=http://127.0.0.1:4200/api

prefect profile create new-profile --from ephemeral
prefect profile use new-profile
prefect config set PREFECT_RESULTS_PERSIST_BY_DEFAULT=true PREFECT_LOGGING_LEVEL="ERROR"

prefect profile inspect
prefect config unset PREFECT_LOGGING_LEVEL -y

Use environment variables

All settings can be overridden by setting the environment variable directly.

Override a setting for a single command

For example, we can temporarily set the logging level through an environment variable so that it only lasts for the duration of the command:

PREFECT_LOGGING_LEVEL="CRITICAL" prefect config view --show-sources

Override settings in a .env file

You can also set environment variables in a .env file, which will be automatically applied when using prefect in that directory.

echo 'PREFECT_LOGGING_LEVEL="CRITICAL"' > .env
prefect config view --show-sources

Environment variables always take precedence

Environment variables always take precedence over values stored within a profile. This allows you to configure certain runtime behavior for your workflows by setting the appropriate environment variable on the job or process executing the workflow.

Commonly configured settings

This section describes some commonly configured settings.

Prefect Cloud

• PREFECT_API_KEY: this setting specifies the API key used to authenticate with Prefect Cloud.
• PREFECT_API_URL: this setting specifies the API endpoint of your Prefect Cloud workspace or a self-hosted Prefect server instance.

Use prefect cloud login to set these values for Prefect Cloud

To set the PREFECT_API_URL and PREFECT_API_KEY for your active profile, run prefect cloud login. Read more about managing API keys.

Prefect server

• PREFECT_HOME: the PREFECT_HOME value specifies the local Prefect directory for configuration files, profiles, and the location of the default Prefect SQLite database.
• PREFECT_API_DATABASE_CONNECTION_URL: the database connection URL for a self-hosted Prefect server instance. Must be provided in a SQLAlchemy-compatible format. Prefect currently supports SQLite and Postgres.

Security settings

Host the UI behind a reverse proxy

When using a reverse proxy (such as Nginx or Traefik) to proxy traffic to a hosted Prefect UI instance, you must also configure the self-hosted Prefect server instance to connect to the API. The PREFECT_UI_API_URL should be set to the external proxy URL.

For example, if your external URL is https://prefect-server.example.com then set PREFECT_UI_API_URL=https://prefect-server.example.com/api for the Prefect server process. You can also set PREFECT_API_URL to the API URL.

This setting is a fallback if PREFECT_UI_API_URL is not set.

CSRF protection settings

If using self-hosted Prefect server, you can configure CSRF protection settings.

• PREFECT_SERVER_CSRF_PROTECTION_ENABLED: activates CSRF protection on the server, requiring valid CSRF tokens for applicable requests. Recommended for production to prevent CSRF attacks. Defaults to False.
• PREFECT_SERVER_CSRF_TOKEN_EXPIRATION: sets the expiration duration for server-issued CSRF tokens, influencing how often tokens need to be refreshed. The default is 1 hour.
• PREFECT_CLIENT_CSRF_SUPPORT_ENABLED: enables or disables CSRF token handling in the Prefect client. When enabled, the client manages CSRF tokens for state-changing API requests. Defaults to True.

By default clients expect that CSRF protection is enabled on the server. If you are running a server without CSRF protection, you can disable CSRF support in the client.