Configure settings and profiles

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)

The prefect profile CLI commands enable you to create, review, and manage 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.

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

​

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.

​

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.