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 usingprefect
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
: thePREFECT_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 toFalse
.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 toTrue
.
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.
Was this page helpful?