Bring your towel and join one of the fastest growing data communities. Welcome to our second-generation open source orchestration platform, a completely rethought approach to dataflow automation.

Prefect Community

<@ULVA73B9P> Why does Prefect ignore PREFECT_HOME and default to using HOME/.prefect?

:white_check_mark: thought for 394.2 seconds

Short answer: In Prefect 3.x, `PREFECT_HOME` no longer controls where Prefect looks for your profiles/config file. That’s why it can look like it’s being “ignored” and Prefect keeps using `~/.prefect`.

What’s going on:
- `PREFECT_HOME` controls Prefect’s runtime home (e.g., local caches, logs, some temp data).
- The location of your profiles file is controlled by a different setting: `PREFECT_PROFILES_PATH` (path to `profiles.toml`). If you don’t set it, Prefect defaults to `~/.prefect/profiles.toml`.
- So if you only set `PREFECT_HOME`, Prefect will still read profiles from `~/.prefect/profiles.toml` unless you explicitly set `PREFECT_PROFILES_PATH`.

Common reasons it seems ignored:
- You wanted to move the profiles file but only set `PREFECT_HOME` (set `PREFECT_PROFILES_PATH` instead).
- The env var wasn’t actually present in the process that started Prefect (not exported, not in the systemd unit, not passed into the Docker container, etc.).
- Set too late: Prefect reads settings at process start; changing env vars after Prefect is imported/started won’t affect that process.
- Putting `PREFECT_HOME` in a `.env` file: `.env` is loaded after the profile is selected, so it cannot influence where Prefect looks for the profile itself.

How to fix based on your goal:
- Move profiles/config away from `~/.prefect`:
  - Set `PREFECT_PROFILES_PATH` to the full path of your `profiles.toml`
  - Example:
    ```
    export PREFECT_PROFILES_PATH=/opt/prefect/profiles.toml
    prefect config view
    ```
- Move Prefect’s runtime home (caches/logs):
  - Set `PREFECT_HOME`:
    ```
    export PREFECT_HOME=/opt/prefect
    prefect config view
    ```

Tips:
- Verify what Prefect sees with:
  ```
  prefect config view
  ```
  It will show the effective values and their sources.
- For services/containers, set env vars in the service definition (systemd `Environment=`) or Docker `environment:`/`-e` flags.
- On Windows PowerShell:
  ```
  $env:PREFECT_PROFILES_PATH = 'C:\prefect\profiles.toml'
  $env:PREFECT_HOME = 'C:\prefect'
  prefect config view
  ```

Docs:
- Settings and profiles in Prefect 3.x: <https://docs-3.prefect.io/v3/concepts/settings-and-profiles|Settings and profiles>

If you share where you set `PREFECT_HOME` (shell, .env, Docker, systemd) and what you’re trying to move (profiles vs. caches/logs), I can give you exact steps.