> ## Documentation Index
> Fetch the complete documentation index at: https://prefect-bd373955-pytest-markdown.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

{/* These settings are type-validated and [documented][prefect.settings.Settings.] */}

## Profiles

You can override a setting with an environment variable or by updating the setting in a Prefect [profile](#configuration-profiles).

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:

```bash
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](#configuring-settings) for details on setting and unsetting configuration values.

### PREFECT\_API\_KEY

The `PREFECT_API_KEY` value specifies the [API key](/3.0rc/manage/cloud/manage-users/api-keys/) used to authenticate with Prefect Cloud.

```bash
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](/3.0rc/manage/cloud/manage-users/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:

```bash
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>](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:

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

<Tip>
  **`PREFECT_API_URL` setting for workers**

  If you're using a [worker](/3.0rc/deploy/work-pools/control-runs/) to run flows in remote environments,
  [`PREFECT_API_URL`](/3.0rc/manage/configure-client/) 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.
</Tip>

### Host the Prefect UI behind a reverse proxy

When using a reverse proxy (such as [Nginx](https://nginx.org) or [Traefik](https://traefik.io)) 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`](../../api-ref/prefect/settings/#PREFECT_UI_API_URL) should be set to the external proxy URL
(for example, if your external URL is \<[https://prefect-server.example.com/>](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`](/3.0rc/manage/configure-client/#prefect.settings.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.

```bash
PREFECT_HOME='~/.prefect'
```

### PREFECT\_LOCAL\_STORAGE\_PATH

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

```bash
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.

```bash
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.

```bash
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.

```bash
PREFECT_CLIENT_CSRF_SUPPORT_ENABLED=True
```

### Database settings

If running a self-hosted Prefect server instance, there are several [database configuration settings](/3.0rc/manage/self-host/) to consider.

### Logging settings

Prefect provides several [logging configuration settings](/3.0rc/develop/logging/).

## 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.

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

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

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

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

```bash
$ 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.

```bash
# 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`.

```bash
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:

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

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

Configure a server instance's port:

```bash
# environment variable
export PREFECT_SERVER_API_PORT=4242
```

```python
# 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:

```bash
$ 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:

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

### Create and remove profiles

Create a new profile with no settings:

```bash
$ 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:

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

Rename a profile:

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

Remove a profile:

```bash
$ prefect profile delete test
Removed profile 'test'.
```

Remove the default profile to reset it:

```bash
$ prefect profile delete default
Reset profile 'default'.
```

### Change values in profiles

Set a value in the current profile:

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

Set multiple values in the current profile:

```bash
$ 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:

```bash
$ 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:

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

### Inspect profiles

See a list of available profiles:

```bash
$ prefect profile ls
* default
cloud
test
local
```

View all settings for a profile:

```bash
$ 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:

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

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

```bash
export PREFECT_PROFILE=foo
```

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

```bash
prefect --profile "foo" ...
```

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

```bash
prefect --profile "foo" flow-run ls
```

You may use the `-p` flag as well:

```bash
prefect -p "foo" flow-run ls
```

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

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

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

The [TOML](https://toml.io/en/) format is used to store profile data.