From a36874734f06be265d78747f426b2164800882e1 Mon Sep 17 00:00:00 2001
From: Izaak Gough <izaak.gough@invertase.io>
Date: Wed, 24 Jun 2026 16:37:36 +0100
Subject: [PATCH 1/5] feat: add python-disable-gunicorn flag

---
 src/commands/emulators-exec.ts    |  1 +
 src/commands/emulators-start.ts   |  1 +
 src/emulator/commandUtils.ts      |  4 ++
 src/emulator/controller.ts        |  1 +
 src/emulator/functionsEmulator.ts | 68 ++++++++++++++++++++++++++++++-
 src/serve/functions.spec.ts       | 13 ++++++
 src/serve/functions.ts            |  1 +
 7 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/src/commands/emulators-exec.ts b/src/commands/emulators-exec.ts
index dadd455bd3a..1224e4f458d 100644
--- a/src/commands/emulators-exec.ts
+++ b/src/commands/emulators-exec.ts
@@ -10,6 +10,7 @@ export const command = new Command("emulators:exec <script>")
   )
   .option(commandUtils.FLAG_ONLY, commandUtils.DESC_ONLY)
   .option(commandUtils.FLAG_INSPECT_FUNCTIONS, commandUtils.DESC_INSPECT_FUNCTIONS)
+  .option(commandUtils.FLAG_PYTHON_DISABLE_GUNICORN, commandUtils.DESC_PYTHON_DISABLE_GUNICORN)
   .option(commandUtils.FLAG_IMPORT, commandUtils.DESC_IMPORT)
   .option(commandUtils.FLAG_EXPORT_ON_EXIT, commandUtils.DESC_EXPORT_ON_EXIT)
   .option(commandUtils.FLAG_VERBOSITY, commandUtils.DESC_VERBOSITY)
diff --git a/src/commands/emulators-start.ts b/src/commands/emulators-start.ts
index 6ddc4f3d135..c168ab619c0 100644
--- a/src/commands/emulators-start.ts
+++ b/src/commands/emulators-start.ts
@@ -22,6 +22,7 @@ export const command = new Command("emulators:start")
   .description("start the local Firebase emulators")
   .option(commandUtils.FLAG_ONLY, commandUtils.DESC_ONLY)
   .option(commandUtils.FLAG_INSPECT_FUNCTIONS, commandUtils.DESC_INSPECT_FUNCTIONS)
+  .option(commandUtils.FLAG_PYTHON_DISABLE_GUNICORN, commandUtils.DESC_PYTHON_DISABLE_GUNICORN)
   .option(commandUtils.FLAG_IMPORT, commandUtils.DESC_IMPORT)
   .option(commandUtils.FLAG_EXPORT_ON_EXIT, commandUtils.DESC_EXPORT_ON_EXIT)
   .option(commandUtils.FLAG_VERBOSITY, commandUtils.DESC_VERBOSITY)
diff --git a/src/emulator/commandUtils.ts b/src/emulator/commandUtils.ts
index 4306ca0fa69..9a09c0cfbe7 100644
--- a/src/emulator/commandUtils.ts
+++ b/src/emulator/commandUtils.ts
@@ -34,6 +34,10 @@ export const FLAG_INSPECT_FUNCTIONS = "--inspect-functions [port]";
 export const DESC_INSPECT_FUNCTIONS =
   "emulate Cloud Functions in debug mode with the node inspector on the given port (9229 if not specified)";
 
+export const FLAG_PYTHON_DISABLE_GUNICORN = "--python-disable-gunicorn";
+export const DESC_PYTHON_DISABLE_GUNICORN =
+  "run Python Functions emulator processes without gunicorn, using the Flask server in non-debug mode";
+
 export const FLAG_IMPORT = "--import [dir]";
 export const DESC_IMPORT = "import emulator data from a previous export (see emulators:export)";
 
diff --git a/src/emulator/controller.ts b/src/emulator/controller.ts
index 493dc0834db..31e8041e8cc 100755
--- a/src/emulator/controller.ts
+++ b/src/emulator/controller.ts
@@ -616,6 +616,7 @@ export async function startAll(
       host: functionsAddr.host,
       port: functionsAddr.port,
       debugPort: inspectFunctions,
+      pythonDisableGunicorn: Boolean(options.pythonDisableGunicorn),
       verbosity: options.logVerbosity,
       projectAlias: options.projectAlias,
       extensionsEmulator: extensionEmulator,
diff --git a/src/emulator/functionsEmulator.ts b/src/emulator/functionsEmulator.ts
index a4fa725986a..bdfe2e44c31 100644
--- a/src/emulator/functionsEmulator.ts
+++ b/src/emulator/functionsEmulator.ts
@@ -1,4 +1,5 @@
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import * as express from "express";
 import * as clc from "colorette";
@@ -70,6 +71,48 @@ import {
 import { ExtensionsEmulator } from "./extensionsEmulator";
 
 const EVENT_INVOKE_GA4 = "functions_invoke"; // event name GA4 (alphanumertic)
+const PYTHON_DISABLE_GUNICORN_ENV = "FIREBASE_FUNCTIONS_EMULATOR_DISABLE_GUNICORN";
+
+// On macOS, gunicorn can trigger fork-safety crashes in Python emulator
+// processes. functions-framework only falls back to Flask in non-debug mode
+// when gunicorn cannot be imported, so the emulator injects this
+// sitecustomize shim to force that fallback without enabling Flask
+// debug/reloader behavior.
+
+const PYTHON_DISABLE_GUNICORN_SHIM = `import builtins
+import os
+
+if os.environ.get("${PYTHON_DISABLE_GUNICORN_ENV}") == "1":
+    _original_import = builtins.__import__
+
+    def _firebase_import_without_gunicorn(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "functions_framework._http.gunicorn":
+            raise ImportError("Gunicorn disabled for local Firebase Functions emulator")
+        return _original_import(name, globals, locals, fromlist, level)
+
+    builtins.__import__ = _firebase_import_without_gunicorn
+`;
+
+let pythonDisableGunicornShimDir: string | undefined;
+
+function getPythonDisableGunicornShimDir(): string {
+  if (!pythonDisableGunicornShimDir) {
+    pythonDisableGunicornShimDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), "firebase-tools-python-shim-"),
+    );
+    fs.writeFileSync(
+      path.join(pythonDisableGunicornShimDir, "sitecustomize.py"),
+      PYTHON_DISABLE_GUNICORN_SHIM,
+      "utf8",
+    );
+  }
+
+  return pythonDisableGunicornShimDir;
+}
+
+function prependPythonPath(envs: Record<string, string | undefined>, injectedPath: string): string {
+  return envs.PYTHONPATH ? `${injectedPath}${path.delimiter}${envs.PYTHONPATH}` : injectedPath;
+}
 
 /*
  * The Realtime Database emulator expects the `path` field in its trigger
@@ -123,6 +166,7 @@ export interface FunctionsEmulatorArgs {
   projectDir: string;
   emulatableBackends: EmulatableBackend[];
   debugPort: number | boolean;
+  pythonDisableGunicorn?: boolean;
   account?: Account;
   port?: number;
   host?: string;
@@ -229,6 +273,7 @@ export class FunctionsEmulator implements EmulatorInstance {
   private dynamicBackends: EmulatableBackend[] = [];
   private watchers: chokidar.FSWatcher[] = [];
   private watchCleanups: Array<() => Promise<void>> = [];
+  private pythonDisableGunicornNoticeLogged = false;
 
   debugMode = false;
 
@@ -1737,7 +1782,7 @@ export class FunctionsEmulator implements EmulatorInstance {
     const port = await portfinder.getPortPromise({
       port: 8081 + randomInt(0, 1000), // Add a small jitter to avoid race condition.
     });
-    const childProcess = runWithVirtualEnv(args, backend.functionsDir, {
+    const pythonRuntimeEnvs: Record<string, string> = {
       ...process.env,
       ...envs,
       // Required to flush stdout/stderr immediately to the piped channels.
@@ -1746,7 +1791,26 @@ export class FunctionsEmulator implements EmulatorInstance {
       DEBUG: "False",
       HOST: "127.0.0.1",
       PORT: port.toString(),
-    });
+    };
+
+    if (this.args.pythonDisableGunicorn) {
+      pythonRuntimeEnvs[PYTHON_DISABLE_GUNICORN_ENV] = "1";
+      pythonRuntimeEnvs.PYTHONPATH = prependPythonPath(
+        pythonRuntimeEnvs,
+        getPythonDisableGunicornShimDir(),
+      );
+
+      if (!this.pythonDisableGunicornNoticeLogged) {
+        this.logger.logLabeled(
+          "BULLET",
+          "functions",
+          "Python emulator gunicorn disabled; using Flask server in non-debug mode.",
+        );
+        this.pythonDisableGunicornNoticeLogged = true;
+      }
+    }
+
+    const childProcess = runWithVirtualEnv(args, backend.functionsDir, pythonRuntimeEnvs);
 
     return {
       process: childProcess,
diff --git a/src/serve/functions.spec.ts b/src/serve/functions.spec.ts
index 1cf99eca41e..1a6def5b802 100644
--- a/src/serve/functions.spec.ts
+++ b/src/serve/functions.spec.ts
@@ -80,6 +80,19 @@ describe("FunctionsServer", () => {
     expect(startRegistryStub).to.have.been.calledOnceWith(functionsEmulatorInstance);
   });
 
+  it("should forward pythonDisableGunicorn to the emulator", async () => {
+    const server = new FunctionsServer();
+    const options = {
+      config: { projectDir: "/path/to/project", src: { functions: {} } },
+      pythonDisableGunicorn: true,
+    };
+
+    await server.start(options as any, {});
+
+    const emulatorArgs = functionsEmulatorStub.getCall(0).args[0];
+    expect(emulatorArgs.pythonDisableGunicorn).to.equal(true);
+  });
+
   it("should assign ports correctly when hosting is running", async () => {
     const server = new FunctionsServer();
     const options = {
diff --git a/src/serve/functions.ts b/src/serve/functions.ts
index ee0a0fa9f6e..4f326e05c83 100644
--- a/src/serve/functions.ts
+++ b/src/serve/functions.ts
@@ -51,6 +51,7 @@ export class FunctionsServer {
       emulatableBackends: this.backends,
       projectAlias: options.projectAlias,
       account,
+      pythonDisableGunicorn: Boolean(options.pythonDisableGunicorn),
       ...partialArgs,
       // Non-optional; parseInspectionPort will set to false if missing.
       debugPort: parseInspectionPort(options),

From 495990d784b8c73224fc3b97c327628967d668ba Mon Sep 17 00:00:00 2001
From: Izaak Gough <izaak.gough@invertase.io>
Date: Thu, 25 Jun 2026 12:33:02 +0100
Subject: [PATCH 2/5] fix: preserve existing sitecustomize

---
 src/emulator/functionsEmulator.ts | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/emulator/functionsEmulator.ts b/src/emulator/functionsEmulator.ts
index bdfe2e44c31..d009ff17c0a 100644
--- a/src/emulator/functionsEmulator.ts
+++ b/src/emulator/functionsEmulator.ts
@@ -80,7 +80,10 @@ const PYTHON_DISABLE_GUNICORN_ENV = "FIREBASE_FUNCTIONS_EMULATOR_DISABLE_GUNICOR
 // debug/reloader behavior.
 
 const PYTHON_DISABLE_GUNICORN_SHIM = `import builtins
+import importlib.machinery
+import importlib.util
 import os
+import sys
 
 if os.environ.get("${PYTHON_DISABLE_GUNICORN_ENV}") == "1":
     _original_import = builtins.__import__
@@ -91,6 +94,26 @@ if os.environ.get("${PYTHON_DISABLE_GUNICORN_ENV}") == "1":
         return _original_import(name, globals, locals, fromlist, level)
 
     builtins.__import__ = _firebase_import_without_gunicorn
+
+_firebase_shim_dir = os.path.dirname(__file__)
+_firebase_remaining_paths = [
+    search_path
+    for search_path in sys.path
+    if os.path.abspath(search_path or os.curdir) != os.path.abspath(_firebase_shim_dir)
+]
+_firebase_user_sitecustomize = importlib.machinery.PathFinder.find_spec(
+    "sitecustomize", _firebase_remaining_paths
+)
+if (
+    _firebase_user_sitecustomize
+    and _firebase_user_sitecustomize.loader
+    and _firebase_user_sitecustomize.origin
+    and os.path.abspath(_firebase_user_sitecustomize.origin) != os.path.abspath(__file__)
+):
+    _firebase_user_sitecustomize_module = importlib.util.module_from_spec(
+        _firebase_user_sitecustomize
+    )
+    _firebase_user_sitecustomize.loader.exec_module(_firebase_user_sitecustomize_module)
 `;
 
 let pythonDisableGunicornShimDir: string | undefined;

From 26fc45792df3a06f16944a5879b7c80440d64b59 Mon Sep 17 00:00:00 2001
From: Izaak Gough <izaak.gough@invertase.io>
Date: Thu, 25 Jun 2026 16:04:50 +0100
Subject: [PATCH 3/5] fix: cleanup temp directory

---
 src/emulator/functionsEmulator.spec.ts | 180 +++++++++++++++++++++++++
 src/emulator/functionsEmulator.ts      |  22 +++
 2 files changed, 202 insertions(+)
 create mode 100644 src/emulator/functionsEmulator.spec.ts

diff --git a/src/emulator/functionsEmulator.spec.ts b/src/emulator/functionsEmulator.spec.ts
new file mode 100644
index 00000000000..bd86c668cd2
--- /dev/null
+++ b/src/emulator/functionsEmulator.spec.ts
@@ -0,0 +1,180 @@
+import { expect } from "chai";
+import * as fs from "fs";
+import * as path from "path";
+import * as portfinder from "portfinder";
+import * as sinon from "sinon";
+
+import { FunctionsEmulator } from "./functionsEmulator";
+import * as functionsPython from "../functions/python";
+
+describe("FunctionsEmulator", () => {
+  const sandbox = sinon.createSandbox();
+
+  afterEach(async () => {
+    sandbox.restore();
+    await makeEmulator(true).stop();
+  });
+
+  function makeEmulator(pythonDisableGunicorn = false): FunctionsEmulator {
+    return new FunctionsEmulator({
+      projectId: "project-id",
+      projectDir: "/workspace",
+      emulatableBackends: [],
+      debugPort: false,
+      pythonDisableGunicorn,
+    });
+  }
+
+  function makePythonBackend() {
+    return {
+      functionsDir: "/workspace/functions",
+      codebase: "default",
+      env: {},
+      secretEnv: [],
+      runtime: "python311",
+    };
+  }
+
+  it("should inject a sitecustomize shim when pythonDisableGunicorn is enabled", async () => {
+    sandbox.stub(portfinder, "getPortPromise").resolves(9191);
+    const runWithVirtualEnv = sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    const mkdtempSync = sandbox.stub(fs, "mkdtempSync").returns("/tmp/firebase-tools-python-shim");
+    const writeFileSync = sandbox.stub(fs, "writeFileSync");
+
+    const emulator = makeEmulator(true);
+    const logLabeled = sandbox.stub((emulator as any).logger, "logLabeled");
+
+    await (emulator as any).startPython(makePythonBackend(), { PYTHONPATH: "/existing/path" });
+
+    expect(runWithVirtualEnv).to.have.been.calledOnce;
+    expect(runWithVirtualEnv.firstCall.args[0]).to.deep.equal(["functions-framework"]);
+    expect(runWithVirtualEnv.firstCall.args[1]).to.equal("/workspace/functions");
+    expect(runWithVirtualEnv.firstCall.args[2]).to.include({
+      FIREBASE_FUNCTIONS_EMULATOR_DISABLE_GUNICORN: "1",
+      PYTHONUNBUFFERED: "1",
+      DEBUG: "False",
+      HOST: "127.0.0.1",
+      PORT: "9191",
+    });
+    expect(runWithVirtualEnv.firstCall.args[2].PYTHONPATH).to.equal(
+      `/tmp/firebase-tools-python-shim${path.delimiter}/existing/path`,
+    );
+    expect(mkdtempSync).to.have.been.calledOnce;
+    expect(writeFileSync).to.have.been.calledOnceWith(
+      "/tmp/firebase-tools-python-shim/sitecustomize.py",
+      sinon.match.string,
+      "utf8",
+    );
+    const shim = writeFileSync.firstCall.args[1];
+    expect(shim).to.include("PathFinder.find_spec(");
+    expect(shim).to.include('"sitecustomize", _firebase_remaining_paths');
+    expect(shim).to.include("module_from_spec");
+    expect(shim).to.include("exec_module");
+    expect(logLabeled).to.have.been.calledOnceWith(
+      "BULLET",
+      "functions",
+      "Python emulator gunicorn disabled; using Flask server in non-debug mode.",
+    );
+  });
+
+  it("should leave python runtime envs unchanged when pythonDisableGunicorn is disabled", async () => {
+    sandbox.stub(portfinder, "getPortPromise").resolves(9292);
+    const runWithVirtualEnv = sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    const mkdtempSync = sandbox.stub(fs, "mkdtempSync");
+    const writeFileSync = sandbox.stub(fs, "writeFileSync");
+
+    const emulator = makeEmulator(false);
+    const logLabeled = sandbox.stub((emulator as any).logger, "logLabeled");
+
+    await (emulator as any).startPython(makePythonBackend(), {});
+
+    expect(runWithVirtualEnv).to.have.been.calledOnce;
+    expect(runWithVirtualEnv.firstCall.args[2]).to.include({
+      PYTHONUNBUFFERED: "1",
+      DEBUG: "False",
+      HOST: "127.0.0.1",
+      PORT: "9292",
+    });
+    expect(runWithVirtualEnv.firstCall.args[2]).to.not.have.property(
+      "FIREBASE_FUNCTIONS_EMULATOR_DISABLE_GUNICORN",
+    );
+    expect(runWithVirtualEnv.firstCall.args[2].PYTHONPATH).to.equal(process.env.PYTHONPATH);
+    expect(mkdtempSync).to.not.have.been.called;
+    expect(writeFileSync).to.not.have.been.called;
+    expect(logLabeled).to.not.have.been.called;
+  });
+
+  it("should recursively remove the shim dir during stop and clear the cached path", async () => {
+    sandbox.stub(portfinder, "getPortPromise").resolves(9393);
+    const runWithVirtualEnv = sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    const mkdtempSync = sandbox.stub(fs, "mkdtempSync");
+    mkdtempSync.onFirstCall().returns("/tmp/firebase-tools-python-shim-one");
+    mkdtempSync.onSecondCall().returns("/tmp/firebase-tools-python-shim-two");
+    sandbox.stub(fs, "writeFileSync");
+    const rmSync = sandbox.stub(fs, "rmSync");
+
+    const emulator = makeEmulator(true);
+
+    await (emulator as any).startPython(makePythonBackend(), {});
+    await emulator.stop();
+    await (emulator as any).startPython(makePythonBackend(), {});
+
+    expect(rmSync).to.have.been.calledOnceWith("/tmp/firebase-tools-python-shim-one", {
+      recursive: true,
+    });
+    expect(mkdtempSync).to.have.been.calledTwice;
+    expect(runWithVirtualEnv.secondCall.args[2].PYTHONPATH).to.equal(
+      "/tmp/firebase-tools-python-shim-two",
+    );
+  });
+
+  it("should ignore ENOENT during shim dir cleanup and clear the cached path", async () => {
+    sandbox.stub(portfinder, "getPortPromise").resolves(9494);
+    const runWithVirtualEnv = sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    const mkdtempSync = sandbox.stub(fs, "mkdtempSync");
+    mkdtempSync.onFirstCall().returns("/tmp/firebase-tools-python-shim-missing");
+    mkdtempSync.onSecondCall().returns("/tmp/firebase-tools-python-shim-recreated");
+    sandbox.stub(fs, "writeFileSync");
+    const rmSync = sandbox.stub(fs, "rmSync").throws(
+      Object.assign(new Error("missing"), { code: "ENOENT" }),
+    );
+
+    const emulator = makeEmulator(true);
+    const log = sandbox.stub((emulator as any).logger, "log");
+
+    await (emulator as any).startPython(makePythonBackend(), {});
+    await emulator.stop();
+    await (emulator as any).startPython(makePythonBackend(), {});
+
+    expect(rmSync).to.have.been.calledOnceWith("/tmp/firebase-tools-python-shim-missing", {
+      recursive: true,
+    });
+    expect(mkdtempSync).to.have.been.calledTwice;
+    expect(runWithVirtualEnv.secondCall.args[2].PYTHONPATH).to.equal(
+      "/tmp/firebase-tools-python-shim-recreated",
+    );
+    expect(log).to.not.have.been.called;
+  });
+
+  it("should log a debug message and continue shutdown when shim dir cleanup fails", async () => {
+    sandbox.stub(portfinder, "getPortPromise").resolves(9595);
+    sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    sandbox.stub(fs, "mkdtempSync").returns("/tmp/firebase-tools-python-shim-error");
+    sandbox.stub(fs, "writeFileSync");
+    const rmSync = sandbox.stub(fs, "rmSync").throws(new Error("permission denied"));
+
+    const emulator = makeEmulator(true);
+    const log = sandbox.stub((emulator as any).logger, "log");
+
+    await (emulator as any).startPython(makePythonBackend(), {});
+    await emulator.stop();
+
+    expect(rmSync).to.have.been.calledOnceWith("/tmp/firebase-tools-python-shim-error", {
+      recursive: true,
+    });
+    expect(log).to.have.been.calledWith(
+      "DEBUG",
+      sinon.match("Failed to clean up python-disable-gunicorn shim dir"),
+    );
+  });
+});
diff --git a/src/emulator/functionsEmulator.ts b/src/emulator/functionsEmulator.ts
index d009ff17c0a..932ebdc5d42 100644
--- a/src/emulator/functionsEmulator.ts
+++ b/src/emulator/functionsEmulator.ts
@@ -133,6 +133,26 @@ function getPythonDisableGunicornShimDir(): string {
   return pythonDisableGunicornShimDir;
 }
 
+function cleanupPythonDisableGunicornShimDir(logDebug: (message: string) => void): void {
+  if (!pythonDisableGunicornShimDir) {
+    return;
+  }
+
+  try {
+    fs.rmSync(pythonDisableGunicornShimDir, { recursive: true });
+    pythonDisableGunicornShimDir = undefined;
+  } catch (e: any) {
+    if (e?.code === "ENOENT") {
+      pythonDisableGunicornShimDir = undefined;
+      return;
+    }
+
+    logDebug(
+      `Failed to clean up python-disable-gunicorn shim dir ${pythonDisableGunicornShimDir}: ${e}`,
+    );
+  }
+}
+
 function prependPythonPath(envs: Record<string, string | undefined>, injectedPath: string): string {
   return envs.PYTHONPATH ? `${injectedPath}${path.delimiter}${envs.PYTHONPATH}` : injectedPath;
 }
@@ -639,6 +659,8 @@ export class FunctionsEmulator implements EmulatorInstance {
     if (this.destroyServer) {
       await this.destroyServer();
     }
+
+    cleanupPythonDisableGunicornShimDir((message) => this.logger.log("DEBUG", message));
   }
 
   async discoverTriggers(

From 121d4c601ef6923683f41354287a90088b7576ed Mon Sep 17 00:00:00 2001
From: Izaak Gough <izaak.gough@invertase.io>
Date: Thu, 25 Jun 2026 16:26:05 +0100
Subject: [PATCH 4/5] chore: fix lint

---
 src/emulator/functionsEmulator.spec.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/emulator/functionsEmulator.spec.ts b/src/emulator/functionsEmulator.spec.ts
index bd86c668cd2..9738b46ecc8 100644
--- a/src/emulator/functionsEmulator.spec.ts
+++ b/src/emulator/functionsEmulator.spec.ts
@@ -135,9 +135,9 @@ describe("FunctionsEmulator", () => {
     mkdtempSync.onFirstCall().returns("/tmp/firebase-tools-python-shim-missing");
     mkdtempSync.onSecondCall().returns("/tmp/firebase-tools-python-shim-recreated");
     sandbox.stub(fs, "writeFileSync");
-    const rmSync = sandbox.stub(fs, "rmSync").throws(
-      Object.assign(new Error("missing"), { code: "ENOENT" }),
-    );
+    const rmSync = sandbox
+      .stub(fs, "rmSync")
+      .throws(Object.assign(new Error("missing"), { code: "ENOENT" }));
 
     const emulator = makeEmulator(true);
     const log = sandbox.stub((emulator as any).logger, "log");

From 85f8e932741de28c9ff29a74f69159324b3cb476 Mon Sep 17 00:00:00 2001
From: Izaak Gough <izaak.gough@invertase.io>
Date: Thu, 25 Jun 2026 16:40:47 +0100
Subject: [PATCH 5/5] fix: preserve sitecustomize import with python gunicorn
 shim

---
 src/emulator/functionsEmulator.spec.ts | 14 +++++++++++---
 src/emulator/functionsEmulator.ts      | 12 ++++++------
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/src/emulator/functionsEmulator.spec.ts b/src/emulator/functionsEmulator.spec.ts
index 9738b46ecc8..4ee1335cc37 100644
--- a/src/emulator/functionsEmulator.spec.ts
+++ b/src/emulator/functionsEmulator.spec.ts
@@ -69,6 +69,7 @@ describe("FunctionsEmulator", () => {
     expect(shim).to.include("PathFinder.find_spec(");
     expect(shim).to.include('"sitecustomize", _firebase_remaining_paths');
     expect(shim).to.include("module_from_spec");
+    expect(shim).to.include('sys.modules["sitecustomize"] = _firebase_user_sitecustomize_module');
     expect(shim).to.include("exec_module");
     expect(logLabeled).to.have.been.calledOnceWith(
       "BULLET",
@@ -156,10 +157,12 @@ describe("FunctionsEmulator", () => {
     expect(log).to.not.have.been.called;
   });
 
-  it("should log a debug message and continue shutdown when shim dir cleanup fails", async () => {
+  it("should recreate the shim dir after cleanup fails with a non-ENOENT error", async () => {
     sandbox.stub(portfinder, "getPortPromise").resolves(9595);
-    sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
-    sandbox.stub(fs, "mkdtempSync").returns("/tmp/firebase-tools-python-shim-error");
+    const runWithVirtualEnv = sandbox.stub(functionsPython, "runWithVirtualEnv").returns({} as any);
+    const mkdtempSync = sandbox.stub(fs, "mkdtempSync");
+    mkdtempSync.onFirstCall().returns("/tmp/firebase-tools-python-shim-error");
+    mkdtempSync.onSecondCall().returns("/tmp/firebase-tools-python-shim-recreated");
     sandbox.stub(fs, "writeFileSync");
     const rmSync = sandbox.stub(fs, "rmSync").throws(new Error("permission denied"));
 
@@ -168,10 +171,15 @@ describe("FunctionsEmulator", () => {
 
     await (emulator as any).startPython(makePythonBackend(), {});
     await emulator.stop();
+    await (emulator as any).startPython(makePythonBackend(), {});
 
     expect(rmSync).to.have.been.calledOnceWith("/tmp/firebase-tools-python-shim-error", {
       recursive: true,
     });
+    expect(mkdtempSync).to.have.been.calledTwice;
+    expect(runWithVirtualEnv.secondCall.args[2].PYTHONPATH).to.equal(
+      "/tmp/firebase-tools-python-shim-recreated",
+    );
     expect(log).to.have.been.calledWith(
       "DEBUG",
       sinon.match("Failed to clean up python-disable-gunicorn shim dir"),
diff --git a/src/emulator/functionsEmulator.ts b/src/emulator/functionsEmulator.ts
index 932ebdc5d42..c15ab74a10b 100644
--- a/src/emulator/functionsEmulator.ts
+++ b/src/emulator/functionsEmulator.ts
@@ -113,6 +113,7 @@ if (
     _firebase_user_sitecustomize_module = importlib.util.module_from_spec(
         _firebase_user_sitecustomize
     )
+    sys.modules["sitecustomize"] = _firebase_user_sitecustomize_module
     _firebase_user_sitecustomize.loader.exec_module(_firebase_user_sitecustomize_module)
 `;
 
@@ -138,18 +139,17 @@ function cleanupPythonDisableGunicornShimDir(logDebug: (message: string) => void
     return;
   }
 
+  const shimDir = pythonDisableGunicornShimDir;
+  pythonDisableGunicornShimDir = undefined;
+
   try {
-    fs.rmSync(pythonDisableGunicornShimDir, { recursive: true });
-    pythonDisableGunicornShimDir = undefined;
+    fs.rmSync(shimDir, { recursive: true });
   } catch (e: any) {
     if (e?.code === "ENOENT") {
-      pythonDisableGunicornShimDir = undefined;
       return;
     }
 
-    logDebug(
-      `Failed to clean up python-disable-gunicorn shim dir ${pythonDisableGunicornShimDir}: ${e}`,
-    );
+    logDebug(`Failed to clean up python-disable-gunicorn shim dir ${shimDir}: ${e}`);
   }
 }