Reference

Dev shell options

Every perSystem.frappe-nix option that configures the development shell, the production package and the container images, with types and defaults.

Updated2026-10-19

Core

The options every bench sets.

Option	Type	Default	Notes
`enable`	bool	`false`	Enable the dev shell and the packages.
`name`	str	required (the normalized `app.name` in app mode)	The project's identity, a slug. It seeds the per-bench port offsets and names the container images, the dev processes' systemd scope and the shell's messages; devenv's own `name` defaults to it. Formerly `benchName`.
`defaultSite`	str	`""`	Frappe's `default_site`, and the shell's `FRAPPE_SITE`. Empty means multi-tenancy, with the site set per shell through `.env`. Formerly `siteName`.
`workspaceRoot`	path or null	`null`	The bench root, where `pyproject.toml` and `apps/` live, usually `./.`. Required in bench mode. It must stay `null` in app mode, where frappe-nix assembles the workspace itself.
`python`	package	`pkgs.python312`	Python interpreter. In app mode, the `app.frappeVersion` preset's.
`nodejs`	package	`pkgs.nodejs_22`	Node.js for frontend builds and the Node realtime server. In app mode, the `app.frappeVersion` preset's.
`esbuildTarget`	str	`"es2022"`	The target Frappe's esbuild pipeline compiles bundles for, exported as `ESBUILD_TARGET` in the dev shell and to `builtBench`. See Asset builds.

App mode

Set app.enable = true in the repository of a single Frappe app. See Develop a single app. workspaceRoot must stay null there.

Option	Type	Default	Notes
`app.enable`	bool	`false`	App mode: this flake is one Frappe app's repository, not a bench.
`app.frappe`	path	(required in app mode)	The Frappe source, as a `flake = false` input.
`app.siblings`	list of `{ name; src; }`	`[ ]`	The other apps the bench should carry, in install order. It is a list and not an attribute set, because that order is the members' order and so the order of `sites/apps.txt`. `name` is the directory name under `apps/`, and `src` is the source, usually a flake input.
`app.frappeVersion`	`develop`, `version-15` or `version-16`	`"version-16"`	The row of `lib/frappe-presets.json` that drives `python`, `nodejs`, `requires-python` and `override-dependencies`. It does not pin Frappe: `app.frappe` does.
`app.src`	path	`inputs.self`	The app's own source, which becomes `apps/<NAME>`. Do not filter it: `app.lockDir` is read out of it.
`app.name`	str	`[project].name` of `app.src`	The app's directory name under `apps/`, which is Frappe's own app name.
`app.lockDir`	str	`"nix"`	Where the generated-but-committed `uv.lock` (and `node-locks/`, for pins without a `yarn.lock`) live, relative to the repo root.
`app.benchDir`	str	`".frappe-nix/bench"`	Where the dev shell materializes the writable bench, relative to the repository root. Gitignore it.
`app.excludeNodeTargets`	list of str	`[ ]`	Top-level directories of the app that are never node targets: no `node_modules`, no fallback lock, no build. An opted-in app's managed `flake.nix` sets `[ "docs-site" ]` while the `docs-site` module is on. See App assets.

The watcher

How the watch process chooses what to rebuild. See Memory and disk.

Option	Type	Default	Notes
`watch.apps`	list of str or null	`null`	Apps the `watch` process rebuilds on save. `null` chooses by publisher (`watch.excludePublishers`). See Memory and disk.
`watch.excludePublishers`	list of str	`[ "Frappe Technologies" ]`	With `watch.apps` `null`, leave out every app whose `hooks.py` `app_publisher` contains one of these, ignoring case. `[ ]` watches everything, as `bench watch` does.
`watch.rtl`	bool	`false`	Also rebuild right-to-left stylesheets on save. `bench build` always builds them.
`watch.nativeSass`	bool	`true` where nixpkgs builds `dart-sass`	Compile the watcher's stylesheets with native Dart Sass (`lib/sass-embedded.nix`) instead of Frappe's JavaScript build of it, 3 to 6 times faster per stylesheet. `bench build` keeps Frappe's compiler.
`watch.python`	bool	`true`	Restart the server on a Python source change: the runtime's `--dev`, or `bench serve`'s reloader with `runtime.enable = false`. `/assets` and `/files` are served either way. Formerly `runtime.dev`.
`watch.reassert.hooks`	list of str	`[ ]`	`bench execute` targets run when `sites/assets/assets.json` names a bundle file that does not exist on disk. Empty by default, so it names no app. Needs `defaultSite`. See Assets. Formerly `assets.reassert.hooks`.
`watch.reassert.debounceMs`	int	`750`	How long `assets.json` must sit unmodified before the bench-watch-driven check re-reads it. Formerly `assets.reassert.debounceMs`.

MariaDB

Option	Type	Default	Notes
`mariadb.package`	package	`pkgs.mariadb`	MariaDB package.
`mariadb.initialDatabases`	list of `{ name }`	`[ ]`	Databases created on the first `devenv up`.
`mariadb.durable`	bool	`false`	Flush InnoDB to disk at every commit and keep the doublewrite buffer, as production does. Off, the log is flushed once a second, which makes commits roughly 30 times faster, at the risk of the last second of commits if the machine crashes. See Memory and disk.
`mariadb.noCow`	bool	`true`	On btrfs, keep the data directory off copy-on-write (`chattr +C`). Set at shell entry on a directory that is missing or empty. One already holding data is reported, and `frappe-nix-db-nocow migrate "$MYSQL_HOME"` moves it once.

Process scope

Runs devenv up in a systemd scope of its own. See Memory and disk.

Option	Type	Default	Notes
`processScope.enable`	bool	`true`	Run `devenv up` in a systemd scope of its own, so the dev stack is not accounted to, and killed along with, the editor that started it. Linux with a systemd user manager and the process-compose manager; a no-op elsewhere.
`processScope.memoryHigh`	str	`"40%"`	The scope's `MemoryHigh=`: past it the dev stack is throttled and reclaimed from first. A percentage is of physical RAM.
`processScope.memoryMax`	str or null	`null`	The scope's `MemoryMax=`, or none.

Node builds

Option	Type	Default	Notes
`nodeOverrides`	attrs of attrs	`{ }`	Per node target (an app, or `app/subdir`): extra attributes for the derivation that runs its `yarn install --offline`, such as `postPatch`, `nativeBuildInputs` or a `yarnOfflineCache` of your own. See Dependencies and locks.
`nodeNestedFrontendExcludes`	list of str	`[ ]`	Nested frontends (`app/subdir`) to leave out: no `node_modules`, no assets, and the parent's build script that drives them is dropped. See Dependencies and locks.

Packages, scripts and environment

Option	Type	Default	Notes
`pythonOverrides`	overlay	no-op overlay	Extra Python package set overlay, on top of the shared fixes and `mysqlclient` (see `lib.overrides`).
`pythonBuildDependencies`	attrs of lists	`{ }`	This bench's own `[tool.uv.extra-build-dependencies]` entries, such as `{ fuuid = [ "poetry-core" ]; }`, in place of the ones derived from `uv.lock`. See Build dependencies.
`extraDevPackages`	list of package	`[ ]`	Extra packages on the dev shell.
`extraContainerRuntimeDeps`	list of package	`[ ]`	Extra runtime packages in production containers.
`extraPackages`	list of package	`[ ]`	Extra packages installed in both the dev shell and any production deployment of this package. The NixOS module reads them off `builtBench`'s `passthru.extraPackages`, so no server-side configuration is needed.
`extraLibraryPaths`	list of package	`[ ]`	Extra `LD_LIBRARY_PATH` entries (dev shell).
`extraScripts`	attrs	`{ }`	Extra devenv scripts, merged over the standard set.
`extraEnv`	attrs of str	`{ }`	Extra environment variables (dev shell).

Runtime

The unified frappe-runtime process. See The unified runtime. The production counterparts are under services.frappe-nix.runtime.

Option	Type	Default	Notes
`runtime.enable`	bool	`true`	Run one `frappe-runtime` process (web, realtime, jobs and scheduler) instead of the split web, socketio, worker and scheduler processes.
`runtime.jobThreads`	int	`2`	Concurrent background jobs inside the runtime process.
`runtime.src`	null or path	`runtime/` in this repository	The source `frappe-runtime` is built from, overriding the revision `uv.lock` resolved. `null` hands control back to `uv.lock`.

Ports and sockets

See The development shell.

Option	Type	Default	Notes
`sockets.enable`	bool	`true`	Put MariaDB, Redis, the realtime server and the web server on unix sockets behind one nginx port, so several benches can run at once. Needs Frappe 15.46 or newer.
`ports.offset`	int, 0–899	a hash of `name`	The offset every preferred TCP port derives from: web `8000 +`, MariaDB `3306 +`, Mailpit `19000`, `20000` and `21000 +`. In app mode with `ports.worktreeSalt`, a linked worktree hashes `<name>@<path>`. In app mode `FRAPPE_NIX_PORT_OFFSET` wins over it.
`ports.worktreeSalt`	bool	whether the app opted in to the app standards	App mode: salt a linked worktree's `ports.offset` with its path, so two worktrees of one app prefer different ports. On by default only with a `[tool.frappe-nix]` table; any app may set it. Bench mode ignores it.
`ports.base`	port or null	`null`	The web port, overriding `8000 + ports.offset`. Mailpit and MariaDB keep theirs. While `ports.strict` is unset, `devenv up` refuses it when it is taken rather than moving it.
`ports.strict`	bool or null	`null`: strict in bench mode, not in app mode	Whether `devenv up` refuses a taken preferred port, naming the bench or process that holds it, instead of leasing the next free one. Bench mode is always strict, because its web port is committed: `false` there is an evaluation error. `FRAPPE_NIX_STRICT_PORTS=1` makes any `devenv up` strict and `=0` lets an app-mode bench move, read when `devenv up` runs. With `sockets.enable = false` the ports are always strict.
`ports.span`	int, 1–1000	`100`	How many ports from the preferred one `devenv up` tries for each service before it gives up.
`ports.http`	port	`ports.base`, else `8000 + ports.offset`	The web port: nginx, or the server itself without sockets. Each `ports.*` below is derived for the module to read; set one (`lib.mkForce`) only to fix that service's port.
`ports.db`	port	`3306 + ports.offset`	MariaDB's port. Unbound in socket mode.
`ports.socketio`	port	`9000 + ports.offset`	The Node realtime server's, with `runtime.enable = false` and no sockets.
`ports.smtp`	port	`19000 + ports.offset`	Mailpit's SMTP port: `mailpit.port`'s default.
`ports.mailUi`	port	`20000 + ports.offset`	Mailpit's web UI: `mailpit.httpPort`'s default.
`ports.pop3`	port	`21000 + ports.offset`	Mailpit's POP3 port: `mailpit.pop3.port`'s default.

The ports.* and mailpit.* port values are what the shell evaluates: the preferred ports. The ports a running bench serves on are in $DEVENV_RUNTIME/frappe-nix/ports.json (also $FRAPPE_NIX_PORTS_FILE), written by the frappe-ports process when devenv up starts and removed when the bench stops:

{ "bench_id": "my-app/devenv-1a2b3c4", "name": "my-app", "root": "/src/my-app", "pid": 41234,
  "web": 8298, "mailpit_smtp": 19297, "mailpit_ui": 20297,
  "preferred": { "web": 8297, "mailpit_smtp": 19297, "mailpit_ui": 20297 }, "moved": { "web": 8297 } }

frappe-nix-ports reads it: with no argument it lists the ports, frappe-nix-ports web prints one, --json the file, and who <port> names the bench (or "a process outside frappe-nix") holding a port. When the bench is not up it prints the preferred ports and exits 3.

Apps and assets

Option	Type	Default	Notes
`appsReconcile.enable`	bool	`defaultSite != ""`	Install whatever `sites/apps.txt` names that `defaultSite`'s site does not have installed yet, on every `devenv up`. See Apps in a bench.
`renamedApps`	attrs of str	`{ }`	Apps renamed in place, `OLD = NEW`: `reconcile-apps` runs `frappe-rename-app --site` before it installs anything. See Renaming an app.
`replacedApps`	attrs of str	`{ }`	Apps replaced by a new app, `OLD = NEW`: `reconcile-apps` installs NEW and uninstalls OLD on a site that has OLD. See Renaming an app.

Mailpit

The mail catcher, as a service. It runs whether or not the mail guard is on, and every process that can send mail starts after it. With the guard on (devguard.mail.enable), every site's outgoing mail goes to it.

Option	Type	Default	Notes
`mailpit.enable`	bool	`true`	Run Mailpit with the bench's processes. Before, it ran only with the mail guard on. Off with the guard on, mail goes to a port nothing listens on.
`mailpit.host`	str	`"127.0.0.1"`	Interface Mailpit binds and the mail guard redirects to. Formerly `devguard.mail.host`.
`mailpit.port`	port	`ports.smtp`	SMTP port, and where the mail guard sends mail. Formerly `devguard.mail.port` (`devguard.mail.smtpPort` before that).
`mailpit.httpPort`	port	`ports.mailUi`	Web UI port. Formerly `devguard.mail.httpPort`.
`mailpit.pop3.enable`	bool	`false`	Serve incoming mail from Mailpit's POP3 listener, and have the mail guard send Frappe's POP3 there instead of refusing it. Formerly `devguard.mail.pop3.enable`.
`mailpit.pop3.port`	port	`ports.pop3`	POP3 port. Formerly `devguard.mail.pop3.port`.
`mailpit.pop3.user`	str	`"dev"`	POP3 username (local development only). Formerly `devguard.mail.pop3.user`.
`mailpit.pop3.password`	str	`"dev"`	POP3 password (local development only). Formerly `devguard.mail.pop3.password`.

Development guard rails

Each guard is independently switchable, and devguard.enable = false turns them all off. See Development guard rails.

Option	Type	Default	Notes
`devguard.enable`	bool	`true`	Master switch for all guard rails. See Development guard rails.
`devguard.egress.enable`	bool	`true`	Refuse every connection the bench's Python opens to anything but this machine.
`devguard.egress.allowHosts`	list of str	`[ ]`	Hostnames (`*.` for subdomains), addresses or CIDRs to let through. Shared with `integrations.allowHosts`.
`devguard.mail.enable`	bool	`true`	Route all outgoing mail to Mailpit (`mailpit.host`:`mailpit.port`), and refuse IMAP and POP3, or serve them from Mailpit with `mailpit.pop3.enable`. Mailpit itself is the `mailpit` tree below.
`devguard.mail.sender`	str	`"notifications@example.com"`	From address used only on sites with no outgoing Email Account at all.
`devguard.mail.unmute`	bool	`true`	Ignore `mute_emails` in `site_config.json`.
`devguard.backups.enable`	bool	`true`	Block Dropbox, S3, Google Drive and Frappe Cloud backup upload.
`devguard.objectstore.enable`	bool	`true`	Never delete from, or overwrite in, the configured S3 bucket.
`devguard.objectstore.mode`	`local` or `push`	`"local"`	`local`: `cloud_storage` writes to local disk. `push`: new files are uploaded to the bucket (additive only).
`devguard.objectstore.conditionalWrites`	bool	`true`	Send `If-None-Match: *` on push-mode writes. Set `false` for Backblaze B2, which answers it with 501.
`devguard.integrations.enable`	bool	`true`	Block outbound HTTP via `frappe.integrations.utils.make_request`.
`devguard.integrations.allowHosts`	list of str	`[ ]`	Hosts to permit anyway. Loopback is always allowed. Shared with `egress.allowHosts`.
`devguard.google.enable`	bool	`true`	Block Google Calendar, Contacts and Drive access.
`devguard.webhooks.enable`	bool	`true`	Drop outbound Webhook requests.
`devguard.plaid.enable`	bool	`true`	Block Plaid bank synchronization.
`devguard.jobs.enable`	bool	`true`	Skip scheduled jobs that reach production services. Formerly `devguard.scheduler.enable`.
`devguard.jobs.blockServerScripts`	bool	`true`	Skip Scheduled Job Types backed by a Server Script. Formerly `devguard.scheduler.blockServerScripts`.
`devguard.jobs.extraBlocked`	list of str	`[ ]`	Extra `Scheduled Job Type.method` values to skip (exact match). Formerly `devguard.scheduler.extraBlockedJobs`.

Restore

How bench restore fetches a production backup. See Restore a production backup.

Option	Type	Default	Notes
`restore.enable`	bool	`frappe-nix.secrets.backupAccess.enable`	Let `bench restore` fetch from the object store. See Restore a production backup.
`restore.prefix`	str	`""`	Path inside the bucket. Normally carried in the secret as `BACKUPS_PREFIX` instead.
`restore.files`	`none`, `private`, `all`, or a bool	`"none"`	File archives to pull by default. They are routinely tens of GB. Formerly `restore.withFiles`.
`restore.neutralize`	bool	`true`	Pause the scheduler and switch mail off in a database fetched from the object store.
`restore.carryConfigKeys`	list of str	`[ "encryption_key" "backup_encryption_key" ]`	Allowlist of keys copied from the backup's site config.
`restore.migrate`	bool	`true`	Run `bench migrate` after restoring.
`restore.requireDevguard`	bool	`true`	Refuse to restore into an unguarded bench (`FRAPPE_NIX_RESTORE_ALLOW_UNGUARDED=1` overrides once).

Offline migrate

Alter large tables online in front of bench migrate. See Migrate large tables online.

Option	Type	Default	Notes
`offlineMigrate.enable`	bool	`false`	Run `bench-offline-migrate` in front of every `bench migrate`, so the ALTERs of large tables cannot lock them. Adds percona-toolkit to the closure.
`offlineMigrate.rowThreshold`	int	`100000`	Rows at which a table is altered online. `0` sends every table with a pending change through pt-online-schema-change. Overridable with `FRAPPE_NIX_OFFLINE_MIGRATE_ROW_THRESHOLD` or `--threshold`.

Containers

See Build production images.

Option	Type	Default	Notes
`containers.enable`	bool	`false`	Build the OCI images.
`containers.registry`	str	`""`	Registry prefix for the image names: `"ghcr.io/avunu"` names them `ghcr.io/avunu/<name>/<role>`. A trailing slash is dropped. frappe-nix does not push. See Build production images.