Configure settings and profiles

Prefect settings let you customize your workflow environment, including working with Prefect server and Prefect Cloud.

Learn how to configure your Prefect local settings to customize your workflow environment.

Profiles

You can override a setting with an environment variable or by updating the setting in a Prefect profile.

Prefect profiles are persisted groups of settings on your local machine. A single profile is always active. Initially, a default profile is active and contains no settings overrides.

To view active settings from the command line, run:

prefect config view --show-defaults

When you switch to a different profile, all of the settings configured in the newly activated profile are applied.

Commonly configured settings

This section describes some commonly configured settings. See Configuring settings for details on setting and unsetting configuration values.

PREFECT_API_KEY

The PREFECT_API_KEY value specifies the API key used to authenticate with Prefect Cloud.

PREFECT_API_KEY="[API-KEY]"

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_API_URL

The PREFECT_API_URL value specifies the API endpoint of your Prefect Cloud workspace or a self-hosted Prefect server instance.

For example, if using Prefect Cloud:

PREFECT_API_URL="https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]"

View your Account ID and Workspace ID in your browser URL within a Prefect Cloud workspace page. For example: <https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here>.

If using a local Prefect server instance, set your API URL like this:

PREFECT_API_URL="http://127.0.0.1:4200/api"

PREFECT_API_URL setting for workers

If you’re using a worker to run flows in remote environments, PREFECT_API_URL must be set for the environment where your worker is running.

For the worker to communicate with Prefect Cloud or a Prefect server instance from a remote execution environment such as a VM or Docker container, you must configure PREFECT_API_URL in that environment.

Host the Prefect UI behind a reverse proxy

When using a reverse proxy (such as Nginx or Traefik) to proxy traffic to a locally-hosted Prefect UI instance, you must also configure the 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.

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_HOME='~/.prefect'

PREFECT_LOCAL_STORAGE_PATH

The PREFECT_LOCAL_STORAGE_PATH value specifies the default location of local storage for flow runs.

PREFECT_LOCAL_STORAGE_PATH='${PREFECT_HOME}/storage'

CSRF Protection Settings

If using a local Prefect server instance, 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_PROTECTION_ENABLED=True

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_SERVER_CSRF_TOKEN_EXPIRATION='3600'  # 1 hour in seconds

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.

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.

PREFECT_CLIENT_CSRF_SUPPORT_ENABLED=True

Database settings

If running a self-hosted Prefect server instance, there are several database configuration settings to consider.

Logging settings

Prefect provides several logging configuration settings.

Configure settings

The prefect config CLI commands enable you to view, set, and unset settings.

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

View settings from the CLI

The prefect config view command displays settings that override default values.

$ prefect config view
PREFECT_PROFILE="default"
PREFECT_LOGGING_LEVEL='DEBUG'

You can show the sources of values with --show-sources:

$ prefect config view --show-sources
PREFECT_PROFILE="default"
PREFECT_LOGGING_LEVEL='DEBUG' (from env)

You can also include default values with --show-defaults:

$ prefect config view --show-defaults
PREFECT_PROFILE='default'
PREFECT_API_KEY='None' (from defaults)
PREFECT_API_REQUEST_TIMEOUT='60.0' (from defaults)
PREFECT_API_URL='None' (from defaults)
...

Set and clear values

The prefect config set command lets you change the value of a default setting.

For example, you can set the PREFECT_API_URL to the location of Prefect server or your Cloud workspace: instances or Prefect Cloud.

# use a local Prefect server
prefect config set PREFECT_API_URL="http://127.0.0.1:4200/api"

# use Prefect Cloud
prefect config set PREFECT_API_URL="https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]"

To configure a setting to use its default value, use prefect config unset.

prefect config unset PREFECT_API_URL

Override defaults with environment variables

All settings have keys that match the environment variable to override them.

For example, to configure the home directory:

# environment variable
export PREFECT_HOME="/path/to/home"

# python
import prefect.settings
prefect.settings.PREFECT_HOME.value()  # PosixPath('/path/to/home')

Configure a server instance’s port:

# environment variable
export PREFECT_SERVER_API_PORT=4242

# python
import prefect
prefect.settings.PREFECT_SERVER_API_PORT.value()  # 4242

Configuration profiles

Prefect allows you to persist settings instead of setting an environment variable each time you open a new shell. Settings are persisted to profiles, which allow you to move between groups of settings quickly.

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

Command	Description
create	Create a new profile.
delete	Delete the given profile.
inspect	Display settings from a given profile; defaults to active.
ls	List profile names.
rename	Change the name of a profile.
use	Switch the active profile.

If you configured settings for a profile, prefect profile inspect displays those settings:

$ prefect profile inspect
PREFECT_PROFILE = "default"
PREFECT_API_KEY = "pnu_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
PREFECT_API_URL = "http://127.0.0.1:4200/api"

You can pass the name of a profile to view its settings:

$ prefect profile create test
$ prefect profile inspect test
PREFECT_PROFILE="test"

Create and remove profiles

Create a new profile with no settings:

$ prefect profile create test
Created profile 'test' at /Users/terry/.prefect/profiles.toml.

Create a new profile foo with settings cloned from an existing default profile:

$ prefect profile create foo --from default
Created profile 'cloud' matching 'default' at /Users/terry/.prefect/profiles.toml.

Rename a profile:

$ prefect profile rename temp test
Renamed profile 'temp' to 'test'.

Remove a profile:

$ prefect profile delete test
Removed profile 'test'.

Remove the default profile to reset it:

$ prefect profile delete default
Reset profile 'default'.

Change values in profiles

Set a value in the current profile:

$ prefect config set VAR=X
Set variable 'VAR' to 'X'
Updated profile 'default'

Set multiple values in the current profile:

$ prefect config set VAR2=Y VAR3=Z
Set variable 'VAR2' to 'Y'
Set variable 'VAR3' to 'Z'
Updated profile 'default'

You can set a value in another profile by passing the --profile NAME option to a CLI command:

$ prefect --profile "foo" config set VAR=Y
Set variable 'VAR' to 'Y'
Updated profile 'foo'

Unset values in the current profile to restore the defaults:

$ prefect config unset VAR2 VAR3
Unset variable 'VAR2'
Unset variable 'VAR3'
Updated profile 'default'

Inspect profiles

See a list of available profiles:

$ prefect profile ls
* default
cloud
test
local

View all settings for a profile:

$ prefect profile inspect cloud
PREFECT_API_URL='https://api.prefect.cloud/api/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
x/workspaces/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
PREFECT_API_KEY='xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'          

Using profiles

The default profile is used by default. There are several methods to switch to another profile.

We recommend using the prefect profile use command with the name of the profile:

$ prefect profile use foo
Profile 'test' now active.

Alternatively, you can set the environment variable PREFECT_PROFILE to the name of the profile:

export PREFECT_PROFILE=foo

Or, specify the profile in the CLI command for one-time usage:

prefect --profile "foo" ...

Note that this option must come before the subcommand. For example, to list flow runs using the profile foo:

prefect --profile "foo" flow-run ls

You may use the -p flag as well:

prefect -p "foo" flow-run ls

You may also create an ‘alias’ to automatically use your profile:

$ alias prefect-foo="prefect --profile 'foo' "
# uses our profile!
$ prefect-foo config view  

Conflicts with environment variables

If setting the profile from the CLI with --profile, environment variables that conflict with settings in the profile are ignored.

In all other cases, environment variables take precedence over the value in the profile.

For example, a value set in a profile is used by default:

$ prefect config set PREFECT_LOGGING_LEVEL="ERROR"
$ prefect config view --show-sources
PREFECT_PROFILE="default"
PREFECT_LOGGING_LEVEL='ERROR' (from profile)

But, setting an environment variable overrides the profile setting:

$ export PREFECT_LOGGING_LEVEL="DEBUG"
$ prefect config view --show-sources
PREFECT_PROFILE="default"
PREFECT_LOGGING_LEVEL='DEBUG' (from env)

Unless the profile is explicitly requested when using the CLI:

$ prefect --profile default config view --show-sources
PREFECT_PROFILE="default"
PREFECT_LOGGING_LEVEL='ERROR' (from profile)

Profile files

Profiles are persisted to the file location specified by PREFECT_PROFILES_PATH. The default location is a profiles.toml file in the PREFECT_HOME directory:

$ prefect config view --show-defaults
...
PREFECT_PROFILES_PATH='${PREFECT_HOME}/profiles.toml'
...

The TOML format is used to store profile data.