[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[NixOS](/kb/nixos/)Set up a reproducible Frappe development environment with frappe-nix

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[NixOS](/kb/nixos/)13 articles

- [Overview](/kb/nixos/)
- [A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)
- [Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)
- [Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)
- [Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)
- [Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)
- [Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)
- [Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)
- [Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)
- [Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)
- [Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)
- [Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)
- [Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)
- [WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In NixOS: 13 articles

[Overview](/kb/nixos/)[A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)[Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)[Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)[Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)[Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)[Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)[Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)[Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)[Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)[Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)[Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)[Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)[WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

NixOSSet up a reproducible Frappe development environment with frappe-nix

Use the frappe-nix flake to run a pinned, reproducible Frappe or ERPNext bench with devenv, uv2nix-managed Python, local services and development guard rails.

UpdatedOct 6, 2026

Applies tofrappe-nix (main branchOctober 2026)Frappe developFrappe version-16Frappe version-15

Tagsnixosfrappedevenvbench

Reading time12 min

On this page[What you get](#what-you-get)[Prerequisites](#prerequisites)[Choose a mode](#choose-a-mode)[Create a new bench](#create-a-new-bench)[Migrate an existing bench](#migrate-an-existing-bench)[Develop a single app](#develop-a-single-app)[Write the flake by hand](#write-the-flake-by-hand)[Options you will touch most](#options-you-will-touch-most)[Start the services and create a site](#start-the-services-and-create-a-site)[Apps added later](#apps-added-later)[Everyday commands](#everyday-commands)[Dependencies and locks](#dependencies-and-locks)[Development guard rails](#development-guard-rails)[Troubleshooting](#troubleshooting)[Related documents](#related-documents)

This document shows how to stand up a Frappe or ERPNext bench with [frappe-nix](https://github.com/Avunu/frappe-nix), a flake-parts module that describes the whole bench declaratively. Use it when you want every developer to get the same Python, Node, MariaDB and Redis, and you want that same description to build production artifacts later. For the reasoning behind the approach, read [Why Nix for Business Systems](/kb/nixos/why-nix-for-business-systems/).

## What you get

frappe-nix replaces `bench init` and a hand-built virtualenv. From one `uv` workspace it provides:

A [devenv](https://devenv.sh/) development shell with MariaDB, Redis, nginx, Mailpit, an asset watcher and the Frappe runtime.

Python environments built by [uv2nix](https://github.com/pyproject-nix/uv2nix) from your committed `uv.lock`. In the dev shell your apps are installed as editable packages, so source edits reload.

A `node_modules` tree for every app. The Nix build makes it from each app's own `yarn.lock`. The dev shell runs a normal online `yarn install` instead, as upstream tooling expects.

A `builtBench` package (`nix build`) with assets compiled, which the NixOS module and the container images consume later.

Development guard rails that stop a bench restored from production from emailing customers or touching production storage.

This document covers the development side. For production, see [Building Production Images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/) and [Running Frappe as a NixOS Service](/kb/nixos/running-frappe-as-a-nixos-service/).

## Prerequisites

You need:

[Nix](https://nixos.org/download.html) with flakes enabled.

[direnv](https://direnv.net/), so the shell loads when you enter the directory. Without it, `nix develop --no-pure-eval` does the same job by hand.

git, since apps are tracked as submodules or as flake inputs.

The generated flake declares the `devenv.cachix.org` binary cache, so Nix may ask you to trust it the first time. The `--no-pure-eval` flag appears in every entry point (`.envrc` and `nix develop`), so keep it when you load the shell by hand.

## Choose a mode

frappe-nix works in two shapes, and the same scaffolding command picks the right one by looking at the target directory. The target is the current directory when it is a bench or a Frappe app, or the directory you name on the command line.

| You have                         | Mode             | What is committed                                                                                     |
| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| A new or empty target directory  | New bench        | `flake.nix`, `pyproject.toml`, `uv.lock`, `sites/apps.txt`, `sites/apps.json`, `apps/*` as submodules |
| An existing `bench init` bench   | Migrate in place | The same files as a new bench, added by the migrator                                                  |
| A single Frappe app's repository | App mode         | `flake.nix`, `nix/uv.lock`, and `nix/node-locks/` only if an app ships no `yarn.lock`                 |

In a bench, the repository is the uv workspace. In app mode there is no bench to commit: frappe-nix assembles one from flake inputs into `.frappe-nix/bench/`, which is gitignored and safe to delete.

## Create a new bench

Run the scaffolder from a parent directory with no target and it prompts for a directory name. It asks for a Frappe version and a set of apps, writes the wrapper flake, adds `frappe` and the apps as git submodules on the matching branch, and runs `uv lock`.

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/frappe-nix</span>
```

For a scripted run, pass everything as flags:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--frappe-version</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">version-15</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--apps</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">erpnext,hrms</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">frappe-bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">frappe-bench</span>
```

The `--frappe-version` flag chooses a preset that fixes the interpreter versions:

| Preset       | Python      | Node        |
| ------------ | ----------- | ----------- |
| `develop`    | `python314` | `nodejs_24` |
| `version-16` | `python314` | `nodejs_24` |
| `version-15` | `python312` | `nodejs_20` |

`--apps` takes bare names (resolved to `frappe/<name>`), `owner/repo`, or full git URLs. `--site` sets the default site name.

Then enter the directory and start the stack:

```
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">cd</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">frappe-bench</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">allow</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">devenv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">up</span>
```

## Migrate an existing bench

Run the same command from inside a classic bench. Do a dry run first to read the plan.

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--dry-run</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/frappe-nix</span>
```

The migrator adds what is missing and never deletes. It stages its work but does not commit, so `git diff --cached` is your review. Add `--commit` if you want it committed for you.

Three behaviors are worth knowing before you run it:

Apps with a usable remote become submodules pinned at their current commit. Apps with no usable remote are vendored: the source is committed into the bench and the nested `.git` moves to `.frappe-nix-backup/`.

A classic `env/` virtualenv is moved to `.frappe-nix-backup/`, because a real `env/` directory defeats the dev shell.

If a `sites/*/site_config.json` is already tracked by git, the migrator reports it and prints the `git rm --cached` command. That file holds the site's encryption key and database password, so untrack it and rotate the credentials.

Note

If any app ships a `package.json` but no `yarn.lock`, run `bench-update --node-locks` inside the dev shell before your first `nix build`. The migration does not generate that fallback lock, because it needs the network.

## Develop a single app

From inside an existing Frappe app repository, run the same command.

```
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">cd</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">APP_REP</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">O</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/frappe-nix</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">allow</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">devenv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">up</span>
```

It writes `flake.nix`, `.envrc` and a managed `.gitignore` block, then runs `nix run .#relock` to create `nix/uv.lock`. It never edits your app's own `pyproject.toml`.

The resulting flake pins Frappe as a non-flake input and sets a handful of options:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">url</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"github:Avunu/frappe-nix"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nixpkgs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">follows</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"frappe-nix/nixpkgs"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> { </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">url</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"github:frappe/frappe/version-16"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">; </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">flake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">false</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">; };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">;</span>

<span style="--shiki-dark:#FFA657;--shiki-light:#953800">perSystem</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> _: {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">siteName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"site1.localhost"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">app</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappeVersion</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"version-16"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">inputs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">frappe</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># siblings = [ { name = "erpnext"; src = inputs.erpnext; } ];</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">;</span>
```

Your repository is symlinked into the generated bench, so edits are live. To move a pin, update the input and re-lock:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">flake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">update</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">frappe</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">.#relock</span>
```

`relock` is a flake app rather than a shell command on purpose. A missing or stale lock fails at evaluation time, and the dev shell that carries `uv` is exactly the thing that will not open.

## Write the flake by hand

A bench flake is a thin wrapper. Because `frappe-nix.lib.mkFlake` merges frappe-nix's own inputs into yours, you only declare `frappe-nix` and a `nixpkgs` that follows it.

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">inputs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># apps/* are git submodules; expose their contents to the flake source tree.</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">self</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">submodules</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">url</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"github:Avunu/frappe-nix"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># flake-parts takes perSystem pkgs from an input literally named nixpkgs.</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nixpkgs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">follows</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"frappe-nix/nixpkgs"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  };</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">outputs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    { self</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">,</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">,</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">... </span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}@inputs:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">frappe-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">lib</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">mkFlake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> { </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">inherit</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">inputs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">; } (</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      { </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">... </span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">imports</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> [ </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">frappe-nix</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">flakeModules</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">default</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ];</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">systems</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> [ </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"x86_64-linux"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"aarch64-linux"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"aarch64-darwin"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"x86_64-darwin"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ];</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">perSystem</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">          { pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">,</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">... </span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">          {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">frappe-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">benchName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"frappe-bench"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">siteName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"site1.localhost"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">workspaceRoot</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">./.</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">python</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">python312</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nodejs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">nodejs_22</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">              </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">mariadb</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">initialDatabases</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> [ { </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"site1_db"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">; } ];</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">          };</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">      }</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    );</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

The `.envrc` is a single line, `use flake . --no-pure-eval`. [Avunu/frappe-devenv](https://github.com/Avunu/frappe-devenv) is the reference bench wired up this way.

### Options you will touch most

| Option                         | Default                            | Purpose                                                                                                     |
| ------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `siteName`                     | `""`                               | Sets `FRAPPE_SITE`. Leave empty for a multi-tenant bench.                                                   |
| `python`, `nodejs`             | `pkgs.python312`, `pkgs.nodejs_22` | Interpreters. In app mode the `frappeVersion` preset chooses them.                                          |
| `mariadb.initialDatabases`     | `[]`                               | Databases created on first `devenv up`.                                                                     |
| `watch.apps`                   | `null`                             | Apps the watcher rebuilds. `null` skips apps published by Frappe Technologies. `[ ]` turns the watcher off. |
| `mariadb.durable`              | `false`                            | Trades crash durability for much faster commits.                                                            |
| `ports.base`                   | `null`                             | First port to try. Defaults to 8000 plus a hash of `benchName`.                                             |
| `sockets.enable`               | `true`                             | Unix sockets behind one nginx port. Needs Frappe 15.46 or newer.                                            |
| `runtime.enable`               | `true`                             | One `frappe-runtime` process instead of split web, socket.io, worker and scheduler processes.               |
| `extraEnv`, `extraDevPackages` | `{}`, `[]`                         | Extra environment variables and packages in the shell.                                                      |

The full option list is in the [frappe-nix README](https://github.com/Avunu/frappe-nix#options--perssystemfrappe-nix).

## Start the services and create a site

`devenv up` starts everything through process-compose. Run it in one terminal and create the site from a second terminal in the same directory.

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">provision-site</span>
```

`provision-site` creates the site named by `FRAPPE_SITE` and installs every app listed in `sites/apps.txt`. It sets the Administrator password to `admin` unless you pass another as the first argument. If the script prompts for a MariaDB root password, leave it blank and press Enter, because the dev MariaDB root has none.

Warning

`provision-site` runs `bench new-site` with `--force`, which drops an existing database for that site. Do not re-run it to pick up a newly added app. See the next section.

Open `http://localhost:<PORT>`. The port is 8000 plus a hash of the bench name, and the shell banner prints it.

| Process                                  | Listens on                                                         |
| ---------------------------------------- | ------------------------------------------------------------------ |
| nginx                                    | TCP 8000 plus the hash. The only port your browser needs.          |
| runtime (web, realtime, jobs, scheduler) | `$DEVENV_RUNTIME/web.sock`                                         |
| MariaDB                                  | `$DEVENV_RUNTIME/mysql.sock` only. No TCP listener.                |
| Redis (cache and queue)                  | `$DEVENV_RUNTIME/redis.sock`                                       |
| Mailpit                                  | TCP 19000 (SMTP), 20000 (web UI), 21000 (POP3), each plus the hash |
| watch                                    | none                                                               |

Because sockets and hashed ports are per bench, you can run several benches at the same time without collisions. The hash comes from the bench name, not the path, so every clone of a bench gets the same ports.

With the default `sockets.enable = true`, MariaDB starts with `skip-networking`, so nothing listens on TCP for it. Frappe itself uses the socket and is unaffected. A tool that opens its own connection to the site config's `db_host` and `db_port` is refused at the bench's own port number, instead of reaching another bench's database on 3306. If you set `sockets.enable = false`, every service goes back to TCP and MariaDB listens on loopback only, on a per-bench port that starts at 3306 plus the hash.

### Apps added later

A site's installed apps live in its database, and nothing installs a newly added app for you in plain Frappe. frappe-nix closes that gap: when `siteName` is set, a `frappe:apps-reconcile` task installs any app from `sites/apps.txt` that the site lacks on every `devenv up`. In a multi-tenant bench, run `reconcile-apps <SITE_NAME>` yourself.

## Everyday commands

The shell puts a `bench` wrapper first on your PATH. Most commands behave as you expect, and a few are redirected to frappe-nix equivalents that understand submodules and the read-only Nix store.

| You run                                               | What happens                                                                                                                                                   |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bench update`                                        | Runs `bench-update`: pull submodules, re-lock what moved, migrate, build. Accepts `--pull`, `--migrate`, `--build` or `--node-locks`, not the stock `--reset`. |
| `bench build`                                         | Brings `node_modules` in step with the apps, then builds.                                                                                                      |
| `bench get-app <URL_OR_ALIAS>`                        | Adds a git submodule and registers it in the uv workspace.                                                                                                     |
| `bench new-app`                                       | Scaffolds a local app and registers it.                                                                                                                        |
| `bench remove-app`                                    | Removes the submodule and its workspace entries.                                                                                                               |
| `bench restore`                                       | Restores a database dump, or fetches the latest backup when you configured backup access.                                                                      |
| `bench migrate`, `bench console`, `bench clear-cache` | Run against `$FRAPPE_SITE`.                                                                                                                                    |
| `bench setup requirements`                            | Verifies `node_modules`, the yarn cache and the Python lock. `--check` changes nothing and exits 1 if something is wrong.                                      |

Everything else, such as `bench serve` or `bench install-app`, goes to the real bench. Interception is subcommand-first, so `bench --site <SITE_NAME> migrate` passes straight through.

In app mode, `bench-update --pull`, `bench-get-app` and `bench-remove-app` refuse and point you at the flake equivalents: `nix flake update`, a new flake input, or editing `frappe-nix.app.siblings`.

## Dependencies and locks

Two lock files carry the dev-to-production contract, and you commit both.

`uv.lock` (or `nix/uv.lock` in app mode) drives the Python environment. When an app gains a dependency, run `uv lock` in the shell. `bench-update --pull` does it for you when a `pyproject.toml` moved.

Each app's own `yarn.lock` drives its `node_modules` in the Nix build. An app that ships none gets a generated fallback in `node-locks/<APP_NAME>/yarn.lock`, created by `bench-update --node-locks`.

A stale `uv.lock` shows up as an evaluation error such as `attribute 'json-repair' missing`. frappe-nix audits the lock first and names the app and the fix. If the shell will not open, run `nix run .#relock` from outside it.

To pick up a newer frappe-nix, update the pin and reload:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">flake</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">update</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">frappe-nix</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">reload</span>
```

If the new version needs something added to your workspace root, entering the shell adds it and runs `uv lock` for you. When it changes files, commit `pyproject.toml` and `uv.lock`, then re-enter the shell.

## Development guard rails

A bench restored from a production backup carries working production credentials. Left alone, it can send real email, delete files from a storage bucket, call payment or calendar integrations and push backups over production's. The `devguard` options stop that. They are on by default, and `devguard.enable = false` turns them all off.

| Guard        | What it stops                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| mail         | All outgoing mail. SMTP goes to Mailpit, and IMAP and POP3 are refused unless you enable Mailpit's POP3. |
| backups      | Dropbox, S3, Google Drive and Frappe Cloud backup uploads.                                               |
| objectstore  | Deleting from or overwriting objects in the configured S3 bucket.                                        |
| integrations | Outbound HTTP through `frappe.integrations.utils.make_request`, except loopback and hosts you allow.     |
| google       | Google Calendar, Contacts and Drive access.                                                              |
| webhooks     | Outbound Webhook requests.                                                                               |
| plaid        | Plaid bank synchronization.                                                                              |
| scheduler    | Scheduled jobs that reach production services.                                                           |

Mail is caught by Mailpit. Open its web UI at the address printed in the shell banner to see what your site tried to send. Local backups, restores and the Backups page keep working, since only egress is blocked.

You can switch guards off for one command without rebuilding:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">FRAPPE_DEVGUARD_DISABLE</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">backups,google</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">console</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">FRAPPE_DEVGUARD_ENABLED</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">console</span>
```

Warning

Only the mail guard works at the transport level. The others patch Frappe and app APIs, so an app nobody has reviewed can still find a way out. Treat the guard rails as a large reduction in risk, not as an airgap.

Restoring production data also carries the production encryption key, which can decrypt every stored credential in the dump. `bench restore` refuses to write that key into a bench with `devguard.enable = false`.

## Troubleshooting

**The shell will not open and the error mentions a missing attribute.** The lock is stale. Run `nix run .#relock`.

**A `node_modules` error from a Vite config several apps deep.** Run `bench setup requirements --node`. Shell entry already deletes known-damaged installs, and this runs the scan on demand.

**Memory pressure while the watcher runs.** The default watcher skips apps published by Frappe Technologies. After editing one of those yourself, run `bench build --app <APP_NAME>`.

**A site page for a new app returns 404.** The app is importable but not installed on the site. Check `reconcile-apps`.

Note

This document was written from a reading of the frappe-nix sources and README, not from a fresh install on a clean machine. Treat exact output as indicative and check the repository for changes since October 2026.

## Related documents

[Building Production Images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/), for the immutable build and OCI images made from the same flake.

[Running Frappe as a NixOS Service](/kb/nixos/running-frappe-as-a-nixos-service/), for deploying a built bench with the `services.frappe` module.

[Bench Operations](/kb/frappe/bench-operations/), for backup, restore and branch-switching procedures on a classic bench.

Sources

- [github.com/Avunu/frappe-nix](https://github.com/Avunu/frappe-nix)
- [github.com/Avunu/frappe-devenv](https://github.com/Avunu/frappe-devenv)
- [flake.parts](https://flake.parts/)
- [devenv.sh](https://devenv.sh/)
- [github.com/pyproject-nix/uv2nix](https://github.com/pyproject-nix/uv2nix)

Need help with NixOS?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousRun WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)[Next →Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [What you get](#what-you-get)
- [Prerequisites](#prerequisites)
- [Choose a mode](#choose-a-mode)
- [Create a new bench](#create-a-new-bench)
- [Migrate an existing bench](#migrate-an-existing-bench)
- [Develop a single app](#develop-a-single-app)
- [Write the flake by hand](#write-the-flake-by-hand)
- [Options you will touch most](#options-you-will-touch-most)
- [Start the services and create a site](#start-the-services-and-create-a-site)
- [Apps added later](#apps-added-later)
- [Everyday commands](#everyday-commands)
- [Dependencies and locks](#dependencies-and-locks)
- [Development guard rails](#development-guard-rails)
- [Troubleshooting](#troubleshooting)
- [Related documents](#related-documents)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
