src: support override option in process.loadEnvFile

Han5991 · IlyasShabi · Han5991 · commit 579c29af1144 · 2026-05-08T20:59:20.000+09:00
Add an opt-in `override` option to `process.loadEnvFile()` and a
matching `--env-file-override-local` CLI flag, allowing values from
`.env` files to replace existing variables in `process.env`.

By default, existing environment variables continue to take
precedence; callers must opt in explicitly. This lets a single
process swap env-file contexts at runtime (integration tests,
monorepo configurations) without manually parsing files via
`util.parseEnv()`.

Co-authored-by: Ilyas Shabi &lt;ilyasshabi94@gmail.com&gt;
Signed-off-by: sangwook &lt;rewq5991@gmail.com&gt;
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -937,6 +937,26 @@ changes:
 Behavior is the same as [`--env-file`][], but an error is not thrown if the file
 does not exist.
 
+### `--env-file-override-local`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+By default, when a variable defined in an env file is already set in the
+environment, the existing value is preserved. Pass
+`--env-file-override-local` together with [`--env-file`][] (or
+[`--env-file-if-exists`][]) to make values from the file override existing
+environment variables instead.
+
+```bash
+BASIC=local node --env-file=.env --env-file-override-local -p 'process.env.BASIC'
+# prints the value from .env, not 'local'.
+```
+
+To override variables at runtime, use the `override` option of
+[`process.loadEnvFile()`][].
+
 ### `--env-file=file`
 
 <!-- YAML
@@ -4391,6 +4411,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`node:ffi`]: ffi.md
 [`node:sqlite`]: sqlite.md
 [`node:stream/iter`]: stream_iter.md
+[`process.loadEnvFile()`]: process.md#processloadenvfilepath-options
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -2753,7 +2753,7 @@ process.kill(process.pid, 'SIGHUP');
 When `SIGUSR1` is received by a Node.js process, Node.js will start the
 debugger. See [Signal Events][].
 
-## `process.loadEnvFile(path)`
+## `process.loadEnvFile(path[, options])`
 
 <!-- YAML
 added:
@@ -2767,7 +2767,10 @@ changes:
     description: This API is no longer experimental.
 -->
 
-* `path` {string | URL | Buffer | undefined}. **Default:** `'./.env'`
+* `path` {string | URL | Buffer | undefined} **Default:** `'./.env'`
+* `options` {Object}
+  * `override` {boolean} If `true`, values from the file replace any matching
+    variable already set in `process.env`. **Default:** `false`.
 
 Loads the `.env` file into `process.env`. Usage of `NODE_OPTIONS`
 in the `.env` file will not have any effect on Node.js.
@@ -2782,6 +2785,38 @@ import { loadEnvFile } from 'node:process';
 loadEnvFile();
 ```
 
+By default, an env file does not override variables that are already set.
+Pass `override: true` to replace them with the values from the file:
+
+```cjs
+const { loadEnvFile } = require('node:process');
+// process.env.API_KEY === 'local-key'
+loadEnvFile('.env', { override: true });
+// process.env.API_KEY now matches the value from .env
+```
+
+```mjs
+import { loadEnvFile } from 'node:process';
+// process.env.API_KEY === 'local-key'
+loadEnvFile('.env', { override: true });
+// process.env.API_KEY now matches the value from .env
+```
+
+When called with options only, the default `'./.env'` path is used:
+
+```cjs
+const { loadEnvFile } = require('node:process');
+loadEnvFile({ override: true });
+```
+
+```mjs
+import { loadEnvFile } from 'node:process';
+loadEnvFile({ override: true });
+```
+
+The same behavior is available at startup via the
+[`--env-file-override-local`][] flag.
+
 ## `process.mainModule`
 
 <!-- YAML
@@ -4613,6 +4648,7 @@ cases:
 [`'exit'`]: #event-exit
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
+[`--env-file-override-local`]: cli.md#--env-file-override-local
 [`--no-deprecation`]: cli.md#--no-deprecation
 [`--permission`]: cli.md#--permission
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
diff --git a/doc/node.1 b/doc/node.1
@@ -571,6 +571,14 @@ node --entry-url 'data:text/javascript,console.log("Hello")'
 Behavior is the same as \fB--env-file\fR, but an error is not thrown if the file
 does not exist.
 .
+.It Fl -env-file-override-local
+Override existing environment variables with values from files supplied via
+\fB--env-file\fR or \fB--env-file-if-exists\fR. Without this flag, existing
+variables take precedence.
+.Bd -literal
+BASIC=local node --env-file=.env --env-file-override-local -p 'process.env.BASIC'
+.Ed
+.
 .It Fl -env-file Ns = Ns Ar file
 Loads environment variables from a file relative to the current directory,
 making them available to applications on \fBprocess.env\fR. The environment
diff --git a/lib/internal/process/per_thread.js b/lib/internal/process/per_thread.js
@@ -45,10 +45,12 @@ const {
     ERR_WORKER_UNSUPPORTED_OPERATION,
   },
 } = require('internal/errors');
-const { emitExperimentalWarning } = require('internal/util');
+const { emitExperimentalWarning, kEmptyObject } = require('internal/util');
+const { isArrayBufferView } = require('internal/util/types');
 const format = require('internal/util/inspect').format;
 const {
   validateArray,
+  validateBoolean,
   validateNumber,
   validateObject,
   validateString,
@@ -60,6 +62,7 @@ const execveDiagnosticChannel = dc.channel('process.execve');
 const constants = internalBinding('constants').os.signals;
 
 let getValidatedPath; // We need to lazy load it because of the circular dependency.
+let URLClass;
 
 const kInternal = Symbol('internal properties');
 
@@ -352,14 +355,29 @@ function wrapProcessMethods(binding) {
   /**
    * Loads the `.env` file to process.env.
    * @param {string | URL | Buffer | undefined} path
+   * @param {{ override?: boolean }} [options]
    */
-  function loadEnvFile(path = undefined) { // Provide optional value so that `loadEnvFile.length` returns 0
+  function loadEnvFile(path = undefined, options = kEmptyObject) {
+    // Provide optional value so that `loadEnvFile.length` returns 0
+    if (arguments.length === 1 &&
+        path !== null && path !== undefined &&
+        typeof path === 'object' &&
+        !isArrayBufferView(path)) {
+      URLClass ??= require('internal/url').URL;
+      if (!(path instanceof URLClass)) {
+        options = path;
+        path = undefined;
+      }
+    }
+    validateObject(options, 'options');
+    const { override = false } = options;
+    validateBoolean(override, 'options.override');
     if (path != null) {
       getValidatedPath ??= require('internal/fs/utils').getValidatedPath;
       path = getValidatedPath(path);
-      _loadEnvFile(path);
+      _loadEnvFile(path, override);
     } else {
-      _loadEnvFile();
+      _loadEnvFile(undefined, override);
     }
   }
 
diff --git a/src/node.cc b/src/node.cc
@@ -337,7 +337,8 @@ MaybeLocal<Value> StartExecution(Environment* env,
   // Without it env is not updated when restarting child process.
   // Child process has --watch flag removed, so it will load the file.
   if (env->options()->has_env_file_string && !env->options()->watch_mode) {
-    per_process::dotenv_file.SetEnvironment(env);
+    per_process::dotenv_file.SetEnvironment(
+        env, env->options()->env_file_override_local);
   }
 
   // TODO(joyeecheung): move these conditions into JS land and let the
diff --git a/src/node_dotenv.cc b/src/node_dotenv.cc
@@ -66,13 +66,13 @@ std::vector<Dotenv::env_file_data> Dotenv::GetDataFromArgs(
   return env_files;
 }
 
-Maybe<void> Dotenv::SetEnvironment(node::Environment* env) {
+Maybe<void> Dotenv::SetEnvironment(node::Environment* env, bool override) {
   auto context = env->context();
   auto env_vars = env->env_vars();
 
   for (const auto& entry : store_) {
     auto existing = env_vars->Get(entry.first.data());
-    if (!existing.has_value()) {
+    if (override || !existing.has_value()) {
       Local<Value> name;
       Local<Value> val;
       if (!ToV8Value(context, entry.first).ToLocal(&name) ||
diff --git a/src/node_dotenv.h b/src/node_dotenv.h
@@ -28,7 +28,7 @@ class Dotenv {
   void ParseContent(const std::string_view content);
   ParseResult ParsePath(const std::string_view path);
   void AssignNodeOptionsIfAvailable(std::string* node_options) const;
-  v8::Maybe<void> SetEnvironment(Environment* env);
+  v8::Maybe<void> SetEnvironment(Environment* env, bool override = false);
   v8::MaybeLocal<v8::Object> ToObject(Environment* env) const;
 
   static std::vector<env_file_data> GetDataFromArgs(
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -899,6 +899,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "set environment variables from supplied file",
             &EnvironmentOptions::optional_env_file);
   Implies("--env-file-if-exists", "[has_env_file_string]");
+  AddOption("--env-file-override-local",
+            "override environment variables already set on the machine with "
+            "values from files supplied via --env-file or --env-file-if-exists",
+            &EnvironmentOptions::env_file_override_local);
+  Implies("--env-file-override-local", "[has_env_file_string]");
   AddOption("--experimental-config-file",
             "set config file path",
             &EnvironmentOptions::experimental_config_file_path,
diff --git a/src/node_options.h b/src/node_options.h
@@ -194,6 +194,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> env_file;
   std::vector<std::string> optional_env_file;
   bool has_env_file_string = false;
+  bool env_file_override_local = false;
   bool test_runner = false;
   uint64_t test_runner_concurrency = 0;
   uint64_t test_runner_timeout = 0;
diff --git a/src/node_process_methods.cc b/src/node_process_methods.cc
@@ -619,20 +619,22 @@ static void Execve(const FunctionCallbackInfo<Value>& args) {
 static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   std::string path = ".env";
-  if (args.Length() == 1) {
+  if (args.Length() >= 1 && !args[0]->IsUndefined()) {
     BufferValue path_value(args.GetIsolate(), args[0]);
     ToNamespacedPath(env, &path_value);
     path = path_value.ToString();
   }
 
+  bool override = args.Length() >= 2 && args[1]->IsTrue();
+
   THROW_IF_INSUFFICIENT_PERMISSIONS(
       env, permission::PermissionScope::kFileSystemRead, path);
 
   Dotenv dotenv{};
 
   switch (dotenv.ParsePath(path)) {
     case dotenv.ParseResult::Valid: {
-      USE(dotenv.SetEnvironment(env));
+      USE(dotenv.SetEnvironment(env, override));
       break;
     }
     case dotenv.ParseResult::InvalidContent: {
diff --git a/test/fixtures/dotenv/assert-basic.js b/test/fixtures/dotenv/assert-basic.js
@@ -0,0 +1,5 @@
+'use strict';
+
+const assert = require('node:assert');
+
+assert.strictEqual(process.env.BASIC, process.env.EXPECTED);
diff --git a/test/fixtures/dotenv/load-env-file-no-override.js b/test/fixtures/dotenv/load-env-file-no-override.js
@@ -0,0 +1,7 @@
+'use strict';
+
+const assert = require('node:assert');
+
+assert.strictEqual(process.env.BASIC, 'Original value');
+process.loadEnvFile(process.argv[2]);
+assert.strictEqual(process.env.BASIC, 'Original value');
diff --git a/test/fixtures/dotenv/load-env-file-options-only.js b/test/fixtures/dotenv/load-env-file-options-only.js
@@ -0,0 +1,7 @@
+'use strict';
+
+const assert = require('node:assert');
+
+assert.strictEqual(process.env.BASIC, 'Original value');
+process.loadEnvFile({ override: true });
+assert.strictEqual(process.env.BASIC, 'basic');
diff --git a/test/fixtures/dotenv/load-env-file-override.js b/test/fixtures/dotenv/load-env-file-override.js
@@ -0,0 +1,7 @@
+'use strict';
+
+const assert = require('node:assert');
+
+assert.strictEqual(process.env.BASIC, 'Original value');
+process.loadEnvFile(process.argv[2], { override: true });
+assert.strictEqual(process.env.BASIC, 'basic');
diff --git a/test/parallel/test-process-load-env-file.js b/test/parallel/test-process-load-env-file.js
@@ -110,3 +110,79 @@ describe('process.loadEnvFile()', () => {
     assert.strictEqual(child.code, 0);
   });
 });
+
+describe('process.loadEnvFile(path, options)', () => {
+  const noOverrideFixture = fixtures.path('dotenv/load-env-file-no-override.js');
+  const overrideFixture = fixtures.path('dotenv/load-env-file-override.js');
+  const optionsOnlyFixture = fixtures.path('dotenv/load-env-file-options-only.js');
+  const assertBasicFixture = fixtures.path('dotenv/assert-basic.js');
+
+  it('does not override an existing env var by default', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ noOverrideFixture, validEnvFilePath ],
+      { env: { ...process.env, BASIC: 'Original value' } },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('overrides an existing env var when override: true', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ overrideFixture, validEnvFilePath ],
+      { env: { ...process.env, BASIC: 'Original value' } },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('supports passing options only', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ optionsOnlyFixture ],
+      {
+        cwd: fixtures.path('dotenv/'),
+        env: { ...process.env, BASIC: 'Original value' },
+      },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('throws when options is not an object', () => {
+    assert.throws(() => {
+      process.loadEnvFile(validEnvFilePath, 'not-an-object');
+    }, { code: 'ERR_INVALID_ARG_TYPE', message: /options/ });
+  });
+
+  it('throws when options.override is not a boolean', () => {
+    assert.throws(() => {
+      process.loadEnvFile(validEnvFilePath, { override: 'yes' });
+    }, { code: 'ERR_INVALID_ARG_TYPE', message: /options\.override/ });
+  });
+
+  it('--env-file-override-local overrides existing env vars from --env-file', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [
+        `--env-file=${validEnvFilePath}`,
+        '--env-file-override-local',
+        assertBasicFixture,
+      ],
+      { env: { ...process.env, BASIC: 'Original value', EXPECTED: 'basic' } },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('--env-file alone keeps existing env vars', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ `--env-file=${validEnvFilePath}`, assertBasicFixture ],
+      { env: { ...process.env, BASIC: 'Original value', EXPECTED: 'Original value' } },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -337,7 +337,8 @@ MaybeLocal<Value> StartExecution(Environment* env,`
`337`	`337`	`// Without it env is not updated when restarting child process.`
`338`	`338`	`// Child process has --watch flag removed, so it will load the file.`
`339`	`339`	`if (env->options()->has_env_file_string && !env->options()->watch_mode) {`
`340`		`- per_process::dotenv_file.SetEnvironment(env);`
	`340`	`+ per_process::dotenv_file.SetEnvironment(`
	`341`	`+ env, env->options()->env_file_override_local);`
`341`	`342`	`}`
`342`	`343`
`343`	`344`	`// TODO(joyeecheung): move these conditions into JS land and let the`