Prefect settings let you customize behavior across different environments.
prefect.toml
file in your project directory. For example:
prefect.toml
or pyproject.toml
for configuration, prefect>=3.1
must be installed.To use a .env
file for configuration, prefect>=3.0.5
must be installed.prefect.toml
files. If you use VSCode, we recommend the Even Better TOML extension.
.env
file: .env
files are useful for declaring local settings that you want to apply across multiple runs.
prefect.toml
file: A prefect.toml
file is useful when you want to declare settings for an entire project. You can keep this file in your project directory and it will be automatically applied regardless of where you run your project.
pyproject.toml
file: If you already have a pyproject.toml
file in your project or like to consolidate settings for all your tools in one place, you can declare settings in the [tool.prefect]
table of your pyproject.toml
file.
Environment variables
.env file in the current working directory
prefect.toml file in the current working directory
pyproject.toml file in the current working directory
Active profile settings
Default values
PREFECT_API_URL
in both your environment and your active profile, the environment variable value will take precedence.
PREFECT_
. They take precedence over all other sources, making them ideal for adjustments that should only apply to a single session or process.
For example, you can run the following command to temporarily set the logging level for a single flow run:
.env
file.env
files are useful for declaring local settings that you want to apply across multiple runs.
When running prefect
in a directory that contains a .env
file, Prefect will automatically apply the settings in the file. We recommend keeping your .env
files local and not committing them to your code repositories.
For example, the following .env
file declares a local setting for the logging level:
.env
file will use the DEBUG
logging level, even if they are run in different shell sessions.
View supported environment variables for each setting in the settings reference documentation.
prefect.toml
fileprefect.toml
file is useful when you want to declare settings for an entire project.
You can keep a prefect.toml
file in your project directory and the declared settings will be automatically applied when running prefect
in that directory. We recommend committing this file to your code repositories to ensure consistency across environments.
For example, the following prefect.toml
file declares a setting for the logging level:
prefect.toml
file to a code repository, creating deployments from flows in that repository will use the settings declared in the prefect.toml
file.
You can see the prefect.toml
path for each setting in the settings reference documentation.
pyproject.toml
filepyproject.toml
file is very similar to declaring settings in a prefect.toml
file. The main difference is that settings are declared in the [tool.prefect]
table instead of at the root of the file.
For example, the following pyproject.toml
file declares a setting for the logging level:
pyproject.toml
file is that it allows you to keep all your dependencies and settings for all your tools in one place. You can learn more about pyproject.toml
files in the Python Packaging User Guide.
~/.prefect/profiles.toml
by default. 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 PREFECT_SERVER_ALLOW_EPHEMERAL_MODE
configured:
PREFECT_SERVER_ALLOW_EPHEMERAL_MODE
?This setting allows a Prefect server to be run ephemerally as needed without explicitly starting a server process.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. |
profiles.toml
file directly:
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. |
ephemeral
profile and then create a new
profile with new settings:
api.url
: this setting specifies the API endpoint of your
Prefect Cloud workspace or a self-hosted Prefect server instance.api.key
: this setting specifies the
API key used to authenticate with Prefect Cloud.home
: the home
value specifies the local Prefect directory for configuration files,
profiles, and the location of the default Prefect SQLite database.prefect cloud login
to set these values for Prefect CloudTo set PREFECT_API_URL
and PREFECT_API_KEY
for your active profile, run prefect cloud login
.
Read more about managing API keys.server.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.