From cd26af171cd1b514d0ebeeab6fcc15432ec10c3c Mon Sep 17 00:00:00 2001
From: Taku Kodma <79110363+risu729@users.noreply.github.com>
Date: Fri, 15 May 2026 02:14:04 +1000
Subject: [PATCH 1/2] docs(config): mark env_file setting deprecated

---
 docs/configuration.md      | 7 +++++--
 docs/environments/index.md | 4 ++--
 schema/mise.json           | 3 ++-
 settings.toml              | 3 +++
 4 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 94fe521e1f..5f3aa7fbbb 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -349,8 +349,6 @@ paranoid = false       # see MISE_PARANOID
 disable_default_registry = false   # disable the default registry, see `MISE_DISABLE_DEFAULT_REGISTRY`
 disable_tools = ['node']           # disable specific tools, generally used to turn off core tools
 
-env_file = '.env' # load env vars from a dotenv file, see `MISE_ENV_FILE`
-
 experimental = true # enable experimental features
 
 # configure messages displayed when entering directories with config files
@@ -360,6 +358,9 @@ status = {
   show_tools = false,
 }
 
+[env]
+_.file = '.env'
+
 # "_" is a special key for information you'd like to put into mise.toml that mise will never parse
 [_]
 foo = "bar"
@@ -526,6 +527,8 @@ This is the path which is used as `{{config_root}}` for the global config file.
 
 ### `MISE_ENV_FILE`
 
+Deprecated. Use `env._.file` in `mise.toml` or `~/.config/mise/config.toml` instead.
+
 Set to a filename to read from env from a dotenv file. e.g.: `MISE_ENV_FILE=.env`.
 Uses [dotenvy](https://crates.io/crates/dotenvy) under the hood.
 
diff --git a/docs/environments/index.md b/docs/environments/index.md
index 1876b9c0a4..7b4566eb86 100644
--- a/docs/environments/index.md
+++ b/docs/environments/index.md
@@ -361,8 +361,8 @@ _.file = [
 ]
 ```
 
-You can set [`MISE_ENV_FILE=.env`](/configuration#mise-env-file) to automatically load dotenv files in any
-directory.
+The legacy [`MISE_ENV_FILE=.env`](/configuration#mise-env-file) setting can also load dotenv
+files automatically, but it is deprecated. Use `env._.file` in a config file instead.
 
 See [secrets](/environments/secrets/) for ways to read encrypted files with `env._.file`.
 
diff --git a/schema/mise.json b/schema/mise.json
index 79ac23f990..83883f528e 100644
--- a/schema/mise.json
+++ b/schema/mise.json
@@ -704,7 +704,8 @@
         },
         "env_file": {
           "description": "Path to a file containing environment variables to automatically load.",
-          "type": "string"
+          "type": "string",
+          "deprecated": true
         },
         "env_shell_expand": {
           "description": "Enable shell-style variable expansion in env values (e.g., $FOO, ${BAR:-default})",
diff --git a/settings.toml b/settings.toml
index fcbb3782f7..d787bcb36c 100644
--- a/settings.toml
+++ b/settings.toml
@@ -519,6 +519,9 @@ env = "MISE_ENV_CACHE_TTL"
 type = "Duration"
 
 [env_file]
+deprecated = "Use env._.file instead."
+deprecated_remove_at = "2027.4.0"
+deprecated_warn_at = "2026.4.17"
 description = "Path to a file containing environment variables to automatically load."
 env = "MISE_ENV_FILE"
 optional = true

From 87a3d92768958d02ca51e25f4a77518d056f9aaf Mon Sep 17 00:00:00 2001
From: Taku Kodma <79110363+risu729@users.noreply.github.com>
Date: Fri, 15 May 2026 02:20:04 +1000
Subject: [PATCH 2/2] docs(config): fix env_file deprecation guidance

---
 settings.toml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/settings.toml b/settings.toml
index d787bcb36c..d51c47aa9d 100644
--- a/settings.toml
+++ b/settings.toml
@@ -520,8 +520,8 @@ type = "Duration"
 
 [env_file]
 deprecated = "Use env._.file instead."
-deprecated_remove_at = "2027.4.0"
-deprecated_warn_at = "2026.4.17"
+deprecated_remove_at = "2027.11.0"
+deprecated_warn_at = "2026.11.0"
 description = "Path to a file containing environment variables to automatically load."
 env = "MISE_ENV_FILE"
 optional = true
@@ -1733,7 +1733,7 @@ env = "MISE_PRERELEASES"
 type = "Bool"
 
 [profile]
-deprecated = "Use MISE_ENV_FILE instead."
+deprecated = "Use env._.file instead."
 description = "Profile to use for mise.${MISE_PROFILE}.toml files."
 env = "MISE_PROFILE"
 hide = true