Project: Prefect (Orchestration & Management / Scheduling & Orchestration)
File: settings.md

description: Prefect settings let you customize your workflow environment, including working with Prefect server and Prefect Cloud. tags: configuration settings environment variables profiles title: Profiles and Configuration search: boost: 2 Learn how to configure your Prefect local settings to customize your workflow environment. These settings are type-validated and . You can override a setting with an environment variable or by updating the setting in a Prefect . 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: <div class="terminal"> ```bash prefect config view --show-defaults ``` </div> When you switch to a different profile, all of the settings configured in the newly activated profile are applied. This section describes some commonly configured settings. See for details on setting and unsetting configuration values. The `PREFECTAPIKEY` value specifies the used to authenticate with Prefect Cloud. ```bash PREFECTAPIKEY="[API-KEY]" ``` To set the `PREFECTAPIURL` and `PREFECTAPIKEY` for your active profile, run `prefect cloud login`. Read more about . The `PREFECTAPIURL` value specifies the API endpoint of your Prefect Cloud workspace or a self-hosted Prefect server instance. For example, if using Prefect Cloud: <div class="terminal"> ```bash PREFECTAPIURL="https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]" ``` </div> 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: <div class="terminal"> ```bash PREFECTAPIURL="http://127.0.0.1:4200/api" ``` </div> !!! tip "`PREFECTAPIURL` setting for workers" If using a (agent and block-based deployments are legacy) that can create flow runs for deployments in remote environments, must be set for the environment in which 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 `PREFECTAPIURL` in that environment. !!! tip "Running the Prefect UI behind a reverse proxy" When using a reverse proxy (such as or ) to proxy traffic to a locally-hosted Prefect UI instance, you must also configure the Prefect server instance to connect to the API. The should be set to the external proxy URL (for example, if your external URL is <https://prefect-server.example.com/> then set `PREFECTUIAPI_URL=https://prefect-server.example.com/api` for the Prefect server process). You can also set to the API URL. This setting is a fallback if `PREFECTUIAPI_URL` is not set. The `PREFECT_HOME` value specifies the local Prefect directory for configuration files, profiles, and the location of the default . ```bash PREFECT_HOME='~/.prefect' ``` The `PREFECTLOCALSTORAGE_PATH` value specifies the default location of local storage for flow runs. ```bash PREFECTLOCALSTORAGEPATH='${PREFECTHOME}/storage' ``` If using a local Prefect server instance, you can configure CSRF protection settings. `PREFECTSERVERCSRFPROTECTIONENABLED` Activates CSRF protection on the server, requiring valid CSRF tokens for applicable requests. Recommended for production to prevent CSRF attacks. Defaults to False. ```bash PREFECTSERVERCSRFPROTECTIONENABLED=True ``` `PREFECTSERVERCSRFTOKENEXPIRATION` Sets the expiration duration for server-issued CSRF tokens, influencing how often tokens need to be refreshed. The default is 1 hour. ```bash PREFECTSERVERCSRFTOKENEXPIRATION='3600' # 1 hour in seconds ``` By default clients expect that CSRF protection is enabled on the

If you are running a server without CSRF protection, you can disable CSRF support in the client. `PREFECTCLIENTCSRFSUPPORTENABLED` 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. ```bash PREFECTCLIENTCSRFSUPPORTENABLED=True ``` If running a self-hosted Prefect server instance, there are several to consider. Prefect provides several . 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. | The `prefect config view` command will display settings that override default values. ```bash $ prefect config view PREFECT_PROFILE="default" PREFECTLOGGINGLEVEL='DEBUG' ``` You can show the sources of values with `--show-sources`: ```bash $ prefect config view --show-sources PREFECT_PROFILE="default" PREFECTLOGGINGLEVEL='DEBUG' (from env) ``` You can also include default values with `--show-defaults`: ```bash $ prefect config view --show-defaults PREFECT_PROFILE='default' PREFECTAGENTPREFETCH_SECONDS='10' (from defaults) PREFECTAGENTQUERY_INTERVAL='5.0' (from defaults) PREFECTAPIKEY='None' (from defaults) PREFECTAPIREQUEST_TIMEOUT='60.0' (from defaults) PREFECTAPIURL='None' (from defaults) ... ``` The `prefect config set` command lets you change the value of a default setting. A commonly used example is setting the `PREFECTAPIURL`, which you may need to change when interacting with different Prefect server instances or Prefect Cloud. ```bash prefect config set PREFECTAPIURL="http://127.0.0.1:4200/api" prefect config set PREFECTAPIURL="https://api.prefect.cloud/api/accounts/[ACCOUNT-ID]/workspaces/[WORKSPACE-ID]" ``` To configure a setting to use its default value, use `prefect config unset`. ```bash prefect config unset PREFECTAPIURL ``` All settings have keys that match the environment variable to override them. For example, to configure the home directory: <div class="terminal"> ```bash export PREFECT_HOME="/path/to/home" ``` </div> ```python import prefect.settings prefect.settings.PREFECT_HOME.value() # PosixPath('/path/to/home') ``` Configure a server instance's port: <div class="terminal"> ```bash export PREFECTSERVERAPI_PORT=4242 ``` </div> ```python prefect.settings.PREFECTSERVERAPI_PORT.value() # 4242 ``` 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: <div class="terminal"> ```bash $ prefect profile inspect PREFECT_PROFILE = "default" PREFECTAPIKEY = "pnu_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" PREFECTAPIURL = "http://127.0.0.1:4200/api" ``` </div> You can pass the name of a profile to view its settings: <div class="terminal"> ```bash $ prefect profile create test $ prefect profile inspect test PREFECT_PROFILE="test" ``` </div> Create a new profile with no settings: <div class="terminal"> ```bash $ prefect profile create test Created profile 'test' at /Users/terry/.prefect/profiles.toml. ``` </div> Create a new profile `foo` with settings cloned from an existing `default` profile: <div class="terminal"> ```bash $ prefect profile create foo --from default Created profile 'cloud' matching 'default' at

``` </div> Rename a profile: <div class="terminal"> ```bash $ prefect profile rename temp test Renamed profile 'temp' to 'test'. ``` </div> Remove a profile: <div class="terminal"> ```bash $ prefect profile delete test Removed profile 'test'. ``` </div> Remove the default profile to reset it: <div class="terminal"> ```bash $ prefect profile delete default Reset profile 'default'. ``` </div> Set a value in the current profile: <div class="terminal"> ```bash $ prefect config set VAR=X Set variable 'VAR' to 'X' Updated profile 'default' ``` </div> Set multiple values in the current profile: <div class="terminal"> ```bash $ prefect config set VAR2=Y VAR3=Z Set variable 'VAR2' to 'Y' Set variable 'VAR3' to 'Z' Updated profile 'default' ``` </div> You can set a value in another profile by passing the `--profile NAME` option to a CLI command: <div class="terminal"> ```bash $ prefect --profile "foo" config set VAR=Y Set variable 'VAR' to 'Y' Updated profile 'foo' ``` </div> Unset values in the current profile to restore the defaults: <div class="terminal"> ```bash $ prefect config unset VAR2 VAR3 Unset variable 'VAR2' Unset variable 'VAR3' Updated profile 'default' ``` </div> See a list of available profiles: <div class="terminal"> ```bash $ prefect profile ls default cloud test local ``` </div> View all settings for a profile: <div class="terminal"> ```bash $ prefect profile inspect cloud PREFECTAPIURL='https://api.prefect.cloud/api/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx x/workspaces/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' PREFECTAPIKEY='xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' ``` </div> 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: <div class="terminal"> ```bash $ prefect profile use foo Profile 'test' now active. ``` </div> Alternatively, you can set the environment variable `PREFECT_PROFILE` to the name of the profile: <div class="terminal"> ```bash export PREFECT_PROFILE=foo ``` </div> Or, specify the profile in the CLI command for one-time usage: <div class="terminal"> ```bash prefect --profile "foo" ... ``` </div> Note that this option must come before the subcommand. For example, to list flow runs using the profile `foo`: <div class="terminal"> ```bash prefect --profile "foo" flow-run ls ``` </div> You may use the `-p` flag as well: <div class="terminal"> ```bash prefect -p "foo" flow-run ls ``` </div> You may also create an 'alias' to automatically use your profile: <div class="terminal"> ```bash $ alias prefect-foo="prefect --profile 'foo' " $ prefect-foo config view ``` </div> 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: <div class="terminal"> ```bash $ prefect config set PREFECTLOGGINGLEVEL="ERROR" $ prefect config view --show-sources PREFECT_PROFILE="default" PREFECTLOGGINGLEVEL='ERROR' (from profile) ``` </div> But, setting an environment variable overrides the profile setting: <div class="terminal"> ```bash $ export PREFECTLOGGINGLEVEL="DEBUG" $ prefect config view --show-sources PREFECT_PROFILE="default" PREFECTLOGGINGLEVEL='DEBUG' (from env) ``` </div> Unless the profile is explicitly requested when using the CLI: <div class="terminal"> ```bash $ prefect --profile default config view --show-sources PREFECT_PROFILE="default" PREFECTLOGGINGLEVEL='ERROR' (from profile) ``` </div> Profiles are persisted to the file location specified by `PREFECTPROFILESPATH`. The default location is a `profiles.toml` file in the `PREFECT_HOME` directory: <div class="terminal"> ```bash $ prefect config view --show-defaults ... PREFECTPROFILESPATH='${PREFECT_HOME}/profiles.toml' ... ``` </div> The format is used to store profile data.