{"id":17492676,"url":"https://github.com/0xc000022070/zen-browser-flake","last_synced_at":"2026-04-19T18:05:14.166Z","repository":{"id":257893994,"uuid":"871476358","full_name":"0xc000022070/zen-browser-flake","owner":"0xc000022070","description":"Community-driven Nix Flake for the Zen browser","archived":false,"fork":false,"pushed_at":"2026-04-08T11:57:21.000Z","size":721,"stargazers_count":854,"open_issues_count":10,"forks_count":80,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-08T13:28:31.653Z","etag":null,"topics":["linux","macos","nix","nix-flake","nix-modules","nixos","zen","zen-browser"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xc000022070.png","metadata":{"files":{"readme":".github/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-12T04:28:19.000Z","updated_at":"2026-04-08T11:57:21.000Z","dependencies_parsed_at":"2026-02-10T09:01:31.361Z","dependency_job_id":null,"html_url":"https://github.com/0xc000022070/zen-browser-flake","commit_stats":{"total_commits":41,"total_committers":13,"mean_commits":"3.1538461538461537","dds":0.7073170731707317,"last_synced_commit":"8146e6a761f9d51f1a93528709733685ff046e2c"},"previous_names":["0xc000022070/zen-browser-flake"],"tags_count":548,"template":false,"template_full_name":null,"purl":"pkg:github/0xc000022070/zen-browser-flake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xc000022070%2Fzen-browser-flake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xc000022070%2Fzen-browser-flake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xc000022070%2Fzen-browser-flake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xc000022070%2Fzen-browser-flake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xc000022070","download_url":"https://codeload.github.com/0xc000022070/zen-browser-flake/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xc000022070%2Fzen-browser-flake/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31875183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","macos","nix","nix-flake","nix-modules","nixos","zen","zen-browser"],"created_at":"2024-10-19T10:05:56.575Z","updated_at":"2026-04-16T07:02:41.908Z","avatar_url":"https://github.com/0xc000022070.png","language":"Nix","funding_links":[],"categories":["Nix","linux"],"sub_categories":[],"readme":"# Zen Browser\n\nThis is a nix flake for the Zen browser.\n\n## Features\n\n- Linux and macOS support\n- Available for _x86_64_ and _aarch64_\n- Support for _twilight_ and _beta_\n- [Policies can be modified via Home Manager and unwrapped package override](#policies)\n- Fast \u0026 Automatic updates via GitHub Actions\n- Browser update checks are disabled by default\n- The default twilight version is reliable and reproducible\n- [Declarative \\[Work\\]Spaces (including themes, icons, containers)](#spaces)\n- [Declarative keyboard shortcuts with version protection](#keyboard-shortcuts)\n- [Declarative mods installation from Zen theme store](#mods)\n\n_A flake for Zen Browser that lets you fine-tune more than other flakes._\n\n## Installation\n\nJust add it to your NixOS `flake.nix` or home-manager:\n\n```nix\ninputs = {\n  zen-browser = {\n    url = \"github:0xc000022070/zen-browser-flake\";\n    inputs = {\n      # IMPORTANT: To ensure compatibility with the latest Firefox version, use nixpkgs-unstable.\n      nixpkgs.follows = \"nixpkgs\";\n      home-manager.follows = \"home-manager\";\n    };\n  };\n  # ...\n}\n```\n\n\u003e [!NOTE]\n\u003e **Beta Branch**: To keep the flake input only sync with beta updates, use\n\u003e `inputs.zen-browser.url = \"github:0xc000022070/zen-browser-flake/beta\"`.\n\n### Integration\n\n\u003e [!IMPORTANT]\n\u003e Use the **twilight** package to guarantee reproducibility, the artifacts of\n\u003e that package are re-uploaded to this repository. However, if you don't agree\n\u003e with that and want to use the official artifacts, use **twilight-official**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch4\u003eHome Manager\u003c/h4\u003e\u003c/summary\u003e\n\n```nix\n{\n  # home.nix\n  imports = [\n    inputs.zen-browser.homeModules.beta\n    # or inputs.zen-browser.homeModules.twilight\n    # or inputs.zen-browser.homeModules.twilight-official\n  ];\n\n  programs.zen-browser = {\n    enable = true;\n    setAsDefaultBrowser = true;\n  };\n}\n```\n\nThen build your Home Manager configuration\n\n```shell\n$ home-manager switch\n```\n\nCheck the [Home Manager Reference](#home-manager-reference) and my rice\n[here](https://github.com/luisnquin/nixos-config/blob/main/home/modules/programs/browser/zen.nix)!\n:)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch4\u003eWith environment.systemPackages or home.packages\u003c/h4\u003e\u003c/summary\u003e\n\nTo integrate `Zen Browser` into your NixOS/Home Manager configuration, add the\nfollowing to your `environment.systemPackages` or `home.packages`:\n\n```nix\n# options are: 'x86_64-linux', 'aarch64-linux' and 'aarch64-darwin'\n\ninputs.zen-browser.packages.\"${system}\".default # beta\ninputs.zen-browser.packages.\"${system}\".beta\ninputs.zen-browser.packages.\"${system}\".twilight\n# IMPORTANT: this package relies on the twilight release artifacts from the\n# official zen repo and those artifacts are always replaced, causing hash mismatch\ninputs.zen-browser.packages.\"${system}\".twilight-official\n\n# you can even override the package policies\ninputs.zen-browser.packages.\"${system}\".default.override {\n  policies = {\n      DisableAppUpdate = true;\n      DisableTelemetry = true;\n      # more and more\n  };\n}\n```\n\nAfterwards you can just build your configuration\n\n```shell\n$ sudo nixos-rebuild switch # or home-manager switch\n```\n\n\u003c/details\u003e\n\n### Start the browser\n\n```shell\n$ zen-beta # or zen-twilight\n```\n\n## Configuration Examples\n\nSee the `examples/` directory for standalone configuration examples:\n\n| Example                                                                       | Description                               |\n| ----------------------------------------------------------------------------- | ----------------------------------------- |\n| [01-basic-home-manager.nix](../examples/01-basic-home-manager.nix)               | Minimal Home Manager setup                |\n| [02-policies-configuration.nix](../examples/02-policies-configuration.nix)       | System policies (policies.json)           |\n| [02a-policies-preferences.nix](../examples/02a-policies-preferences.nix)         | Locked preferences (policies.Preferences) |\n| [02b-settings-preferences.nix](../examples/02b-settings-preferences.nix)         | User settings (profiles.\\*.settings)      |\n| [03-policies-package-override.nix](../examples/03-policies-package-override.nix) | Package-level policy override             |\n| [04-extensions.nix](../examples/04-extensions.nix)                               | Firefox addons                            |\n| [04b-extensions-rycee.nix](../examples/04b-extensions-rycee.nix)                 | Firefox addons via rycee.nix              |\n| [05-mods-installation.nix](../examples/05-mods-installation.nix)                 | Zen theme store mods                      |\n| [06-search-engines.nix](../examples/06-search-engines.nix)                       | Custom search engines                     |\n| [07-bookmarks.nix](../examples/07-bookmarks.nix)                                 | Bookmark organization                     |\n| [08-containers.nix](../examples/08-containers.nix)                               | Multi-container setup                     |\n| [09-spaces-themes.nix](../examples/09-spaces-themes.nix)                         | Spaces with themes                        |\n| [10-pinned-tabs.nix](../examples/10-pinned-tabs.nix)                             | Pinned tabs and folders                   |\n| [11-keyboard-shortcuts.nix](../examples/11-keyboard-shortcuts.nix)               | Keyboard shortcut overrides               |\n| [12-userchrome-css.nix](../examples/12-userchrome-css.nix)                       | userChrome CSS customization              |\n| [13-complete-setup.nix](../examples/13-complete-setup.nix)                       | Full real-world configuration             |\n| [14-native-messaging.nix](../examples/14-native-messaging.nix)                   | Native messaging hosts (1Password, etc.)  |\n\n## Home Manager Reference\n\nThis module is based on Home Manager's\n[mkFirefoxModule](https://github.com/nix-community/home-manager/blob/67f60ebce88a89939fb509f304ac554bcdc5bfa6/modules/programs/firefox/mkFirefoxModule.nix#L207).\nRefer to the examples above for common patterns.\n\nCore options:\n\n- `enable` (boolean): Enable Home Manager config\n- `setAsDefaultBrowser` (boolean): Set Zen as default for URLs and file types\n\n\u003e [!IMPORTANT]\n\u003e macOS users need to configure `programs.zen-browser.darwinDefaultsId` first.\n\u003e See [home-manager options](https://home-manager-options.extranix.com/?query=programs.firefox.darwinDefaultsId\u0026release=master).\n\n## Configuration Layers\n\nThree distinct configuration layers, stored differently:\n\n| Layer                  | File                                                                    | Storage       | User Can Override |\n| ---------------------- | ----------------------------------------------------------------------- | ------------- | ----------------- |\n| **System Policies**    | [02-policies-configuration.nix](../examples/02-policies-configuration.nix) | policies.json | No (enforced)     |\n| **Locked Preferences** | [02a-policies-preferences.nix](../examples/02a-policies-preferences.nix)   | policies.json | No (enforced)     |\n| **User Settings**      | [02b-settings-preferences.nix](../examples/02b-settings-preferences.nix)   | prefs.js      | Yes (defaults)    |\n\n## Profile Configuration\n\nProfiles support many sub-options. See examples directory for:\n\n- **Extensions**: [04-extensions.nix](../examples/04-extensions.nix), [04b-extensions-unfree.nix](../examples/04b-extensions-unfree.nix) (rycee's NUR)\n- **Mods**: [05-mods-installation.nix](../examples/05-mods-installation.nix) (Zen theme store)\n- **Search**: [06-search-engines.nix](../examples/06-search-engines.nix) (custom search shortcuts)\n- **Bookmarks**: [07-bookmarks.nix](../examples/07-bookmarks.nix)\n- **Containers**: [08-containers.nix](../examples/08-containers.nix)\n- **Spaces**: [09-spaces-themes.nix](../examples/09-spaces-themes.nix) with custom gradient themes\n- **Pinned Tabs**: [10-pinned-tabs.nix](../examples/10-pinned-tabs.nix) with folder grouping\n- **Keyboard Shortcuts**: [11-keyboard-shortcuts.nix](../examples/11-keyboard-shortcuts.nix)\n- **userChrome.css**: [12-userchrome-css.nix](../examples/12-userchrome-css.nix)\n\n### Browser State Management\n\n\u003e [!CRITICAL]\n\u003e **Close Zen browser before `home-manager switch`** if you declare:\n\u003e\n\u003e - Any `spaces` (with or without `spacesForce`)\n\u003e - Any `pins` (with or without `pinsForce`)\n\u003e - Any `containers` (with or without `containersForce`)\n\u003e - Any `keyboardShortcuts`\n\nIf you only declare simple options like policies/extensions/bookmarks, rebuilding while Zen is open is ok, and closure won't be required.\n\nSpaces, pins, and containers are stored in `zen-sessions.jsonlz4` (Mozilla LZ4 compressed JSON). The activation script:\n\n1. Checks if Zen is running via `pgrep \"zen\"`—exits with error if browser is open\n2. Decompresses zen-sessions.jsonlz4 from LZ4 to JSON\n3. Modifies it with jq to apply your declared config\n4. Recompresses back to LZ4\n5. Restores backup on any failure\n\nBrowser must be closed because the file is locked in memory while Zen runs. The `*Force` options just control whether undeclared items are deleted—the state modification happens either way.\n\n## Showcase\n\nHere are some user configurations that showcase different setups using this flake:\n\n- [ch1bo](https://github.com/ch1bo/dotfiles/blob/master/home-modules/browser/zen.nix)\n- [luisnquin](https://github.com/luisnquin/nixos-config/blob/main/home/modules/programs/browser/zen/default.nix)\n- [skifli](https://github.com/skifli/nixos/blob/main/users/programs/browser/zen.nix)\n\n## 1Password\n\nZen has to be manually added to the list of browsers that 1Password will\ncommunicate with. See [this wiki article](https://wiki.nixos.org/wiki/1Password)\nfor more information. To enable 1Password integration, you need to add the\nbrowser identifier to the file `/etc/1password/custom_allowed_browsers`.\n\n```nix\nenvironment.etc = {\n  \"1password/custom_allowed_browsers\" = {\n    text = ''\n      .zen-wrapped\n    ''; # or just \"zen\" if you use unwrapped package\n    mode = \"0755\";\n  };\n};\n```\n\n## Native Messaging\n\nTo\n[enable communication between the browser and native applications](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging),\nyou can use the following configuration pattern.\n\n### With Home Manager\n\nCheck the [Home Manager Reference](#home-manager-reference).\n\n### With package override\n\n```nix\n{\n  home.packages = [\n    (\n      inputs.zen-browser.packages.\"${system}\".default.override {\n        nativeMessagingHosts = [pkgs.firefoxpwa];\n      }\n    )\n  ];\n}\n```\n\n## Troubleshooting\n\n### Missing configuration after update\n\n1. The release [18.18.6b](****https://github.com/zen-browser/desktop/releases/tag/1.18.6b)\n   changed the configuration location.\n   Please move your configuration from ~/.zen to ~/.config/zen and restart the browser\n\n   ```bash\n   mkdir -p ~/.config/zen\n   mv ~/.zen/* ~/.config/zen/\n   rmdir ~/.zen\n   ```\n\n   Then change every occurrence of \".zen\" to \".config/zen\" in:\n   - `.config/zen/\u003cprofile_name\u003e/extensions.json`\n   - `.config/zen/\u003cprofile_name\u003e/pkcs11.txt`\n   - `.config/zen/\u003cprofile_name\u003e/chrome_debugger_profile/pkcs11.txt`\n\n   Then run zen in safe mode once and close it (it will perform the required migrations):\n\n   ```bash\n   # or zen-twilight\n   zen-beta --safe-mode\n   ```\n\n2. Please check that you're using the wrapped version of the package.\n   The -unwrapped variants should not be used directly. Instead, they should be wrapped with wrapFirefox or custom wrappers.\n\nAlternatively, you can review [this discussion](https://github.com/zen-browser/desktop/discussions/12366#discussioncomment-15810794) in the official Zen Browser repository.\n\n#### The requested URL returned error: 404\n\nThis usually happens when the Zen team deletes a beta release from the official\nrepository. They do this to keep only stable artifacts available. See\n[#105](https://github.com/0xc000022070/zen-browser-flake/issues/105#issuecomment-3243452133)\nand\n[#112](https://github.com/0xc000022070/zen-browser-flake/issues/112#issuecomment-3262519193)\nfor further context.\n\nYou can either revert your nix input update or wait until CI refreshes\n[sources.json](../sources.json).\n\n#### Zen not seeing my GPU\n\nMake sure that you update your flake.lock as to sync up nixpkgs version. Or make\nzen follow your system nixpkgs by using `inputs.nixpkgs.follows = \"nixpkgs\"`\n(assuming your nixpkgs input is named nixpkgs).\n\nCheck\n[No WebGL context](https://github.com/0xc000022070/zen-browser-flake/issues/86)\nfor details.\n\n#### 1Password constantly requires password\n\nYou may want to set `policies.DisableAppUpdate = false;` in your policies.json\nfile. See [#48](https://github.com/0xc000022070/zen-browser-flake/issues/48).\n\n## Contributing\n\nBefore contributing, please make sure that your code is formatted correctly by\nrunning\n\n```shell\n$ nix fmt\n```\n\n## LICENSE\n\nThis project is licensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xc000022070%2Fzen-browser-flake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xc000022070%2Fzen-browser-flake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xc000022070%2Fzen-browser-flake/lists"}