{"id":14991450,"url":"https://github.com/nvmd/nixos-raspberrypi","last_synced_at":"2026-04-11T22:18:02.331Z","repository":{"id":255195629,"uuid":"818453294","full_name":"nvmd/nixos-raspberrypi","owner":"nvmd","description":"Nix flake for a fully declarative NixOS on Raspberry Pi","archived":false,"fork":false,"pushed_at":"2025-09-27T10:27:24.000Z","size":318,"stargazers_count":245,"open_issues_count":31,"forks_count":28,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-10-09T02:09:03.537Z","etag":null,"topics":["nix-flake","nixos","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nvmd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-06-21T22:31:04.000Z","updated_at":"2025-10-06T13:59:43.000Z","dependencies_parsed_at":"2024-09-28T11:00:46.434Z","dependency_job_id":"8309381b-c524-46c5-965f-79d9d73e4eda","html_url":"https://github.com/nvmd/nixos-raspberrypi","commit_stats":{"total_commits":153,"total_committers":2,"mean_commits":76.5,"dds":"0.019607843137254943","last_synced_commit":"0b19e11b724645406ad5dd61cca803d49a934c7b"},"previous_names":["nvmd/nixos-raspberrypi"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nvmd/nixos-raspberrypi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvmd%2Fnixos-raspberrypi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvmd%2Fnixos-raspberrypi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvmd%2Fnixos-raspberrypi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvmd%2Fnixos-raspberrypi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nvmd","download_url":"https://codeload.github.com/nvmd/nixos-raspberrypi/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvmd%2Fnixos-raspberrypi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000773,"owners_count":26082906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"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":["nix-flake","nixos","raspberry-pi"],"created_at":"2024-09-24T14:35:07.483Z","updated_at":"2026-04-11T22:18:02.309Z","avatar_url":"https://github.com/nvmd.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nixos-raspberrypi\n\nUnopinionated Nix flake for infrastructure, vendor packages, kernel, and some optimized third-party packages for [NixOS](https://nixos.org/) running on Raspberry Pi devices.\n\nIt will let you deploy [NixOS](https://nixos.org/) fully declaratively in one step with tools like [nixos-anywhere](https://github.com/nix-community/nixos-anywhere/) (note: `kexec` is, unfortunately, not supported)\n\n## Provides bootloader infrastructure\n\nManages Raspberry Pi firmware partition `/boot/firmware` (the path is configurable with `boot.loader.raspberry-pi.firmwarePath`).\n\nPartition provisioning is integrated with bootloader activation scripts, happening on NixOS generation switch, enabling to use deployment tools like `nixos-anywhere` without any interactive intervention.\n\nSupported boot methods (configurable with `boot.loader.raspberry-pi.bootloader`):\n- `kernelboot` (legacy), default for RPi5\n- `uboot`, default bootloader for all other boards\n- `kernel`, new generation of `kernelboot`, supporting multiple NixOS generations (see #60), default for RPi5 sd-image/installer images, _recommended_ for new installations.\n\n\n## Provides vendor kernel packages with matched firmware\n\n`pkgs.linuxAndFirmware.default` contains compatible:\n```nix\nlinuxPackages_rpi\u003cboard model\u003e  # Linux kernel\nraspberrypifw                   # Raspberry firmware, device trees (DTBs), device overlays\nraspberrypiWirelessFirmware     # wireless firmware\n```\n\nLatest stable version compatible with the board is selected in the flake module by default.\n\n## Provides 3rd-party optimised packages\n\noverlays, containing vendor, and optimized packages, like `libcamera`, `ffmpeg`, etc.\n\n# Usage\n\n## Adding flake input\n\n```nix\ninputs = {\n  # follow `main` branch of this repository, considered being stable\n  nixos-raspberrypi.url = \"github:nvmd/nixos-raspberrypi/main\";\n};\n\n# Optional: Binary cache for the flake\nnixConfig = {\n  extra-substituters = [\n    \"https://nixos-raspberrypi.cachix.org\"\n  ];\n  extra-trusted-public-keys = [\n    \"nixos-raspberrypi.cachix.org-1:4iMO9LXa8BqhU+Rpg6LQKiGa2lsNh/j2oiYLNOQ5sPI=\"\n  ];\n};\n```\n\n## Using the flake to create NixOS configuration\n\nThere're helper functions intended to be used as a drop-in replacement for\n`nixpkgs.lib.nixosSystem`:\n\n- `nixos-raspberrypi.lib.nixosSystem`\n- `nixos-raspberrypi.lib.nixosSystemFull` - same as above, but with RPi-optimized overlays applied globally, this may lead to more rebuilds\n- `nixos-raspberrypi.lib.nixosInstaller` - same as `nixosSystemFull` but with additional installer-specific modules\n\nAll of them take the following additional optional arguments:\n\n- `nixpkgs` – default = nixpkgs of the `nixos-raspberrypi` will be used\n- `trustCaches` – default=true, trust binary caches of `nixos-raspberrypi`\n\n```nix\nnixosConfigurations.rpi5-demo = nixos-raspberrypi.lib.nixosSystem {\n  specialArgs = inputs;\n  modules = [\n    {\n      # Hardware specific configuration, see section below for a more complete\n      # list of modules\n      imports = with nixos-raspberrypi.nixosModules; [\n        raspberry-pi-5.base\n        raspberry-pi-5.page-size-16k\n        raspberry-pi-5.display-vc4\n        raspberry-pi-5.bluetooth\n      ];\n    }\n\n    ({ config, pkgs, lib, ... }: {\n      networking.hostName = \"rpi5-demo\";\n\n      system.nixos.tags = let\n        cfg = config.boot.loader.raspberry-pi;\n      in [\n        \"raspberry-pi-${cfg.variant}\"\n        cfg.bootloader\n        config.boot.kernelPackages.kernel.version\n      ];\n    })\n\n    # ...\n\n  ];\n};\n```\n\nSee also: \u003chttps://github.com/nvmd/nixos-raspberrypi-demo\u003e, [Installers and examples](#installer-configurations-and-configuration-examples).\n\n## Choosing modules corresponding to your hardware\n\nSee `flake.nix`, `nixosModules` for a full list of configuration modules for your hardware.\nHere is the list of the most important:\n\n```nix\nimports = with nixos-raspberrypi.nixosModules; [\n  # Base board support modules\n  raspberry-pi-02.base\n  raspberry-pi-3.base\n  raspberry-pi-4.base\n  raspberry-pi-5.base\n\n  # (Potentially) All boards\n  usb-gadget-ethernet # Configures USB Gadget/Ethernet - Ethernet emulation over USB\n\n  # RPi4:\n  # import this if you have the display, on rpi4 this is the only display configuration option\n  raspberry-pi-4.display-vc4\n\n  # RPi5:\n  raspberry-pi-5.page-size-16k  # Recommended: optimizations and fixes for issues arising from 16k memory page size (only for systems running default rpi5 (bcm2712) kernel)\n  # use one of following for the \"PrimaryGPU\" configuration:\n  raspberry-pi-5.display-vc4  # \"regular\" display connected\n  raspberry-pi-5.display-rp1  # for RP1-connected (DPI/composite/MIPI DSI) display\n];\n```\n\n## Configure the bootloader and firmware (`config.txt`)\n\nSane default configuration is provided by the base module for a corresponding Raspberry board, but further configuration is, of course, possible:\n\nConfiguration options for the bootloader are in `boot.loader.raspberry-pi` (defined in `modules/system/boot/loader/raspberrypi/default.nix`).\n\nRaspberry's `config.txt` can be configured with `hardware.raspberry-pi.config` options, see `modules/configtxt.nix` as an example (this is the default configuration as provided by RaspberryPi OS, but translated to nix format).\n\n## Options for advanced usage\n\nOptions for a more fine-grained control:\n\n- see implementation details in `lib/default.nix`, `lib/internal.nix`\n- Use `nixos-raspberrypi.lib.int.nixosSystemRPi` instead of `nixos-raspberrypi.lib.nixosSystem`\n- Use regular `nixpkgs.lib.nixosSystem` importing the modules manually, see\nbelow\n\n\u003e [!IMPORTANT]\n\u003e When using `nixpkgs.lib.nixosSystem` directly you **must** pass\n\u003e `nixos-raspberrypi` in `specialArgs` so that board modules can find the\n\u003e flake reference:\n\u003e ```nix\n\u003e nixpkgs.lib.nixosSystem {\n\u003e   specialArgs = { inherit (inputs) nixos-raspberrypi; };\n\u003e   modules = [ ... ];\n\u003e };\n\u003e ```\n\u003e The `nixos-raspberrypi.lib.nixosSystem` helpers do this automatically.\n\n```nix\nimports = with nixos-raspberrypi.nixosModules; [\n\n  # Required: Add necessary overlays with kernel, firmware, vendor packages\n  nixos-raspberrypi.lib.inject-overlays\n\n  # Binary cache with prebuilt packages for the currently locked `nixpkgs`,\n  # see `devshells/nix-build-to-cachix.nix` for a list\n  trusted-nix-caches\n\n  # Optional: All RPi and RPi-optimised packages to be available in `pkgs.rpi`\n  nixpkgs-rpi\n\n  # Optonal: add overlays with optimised packages into the global scope\n  # provides: ffmpeg_{4,6,7}, kodi, libcamera, vlc, etc.\n  # This overlay may cause lots of rebuilds (however many\n  #  packages should be available from the binary cache)\n  nixos-raspberrypi.lib.inject-overlays-global\n];\n```\n\n# Installer configurations\n\nThe flake provides installation SD card images for Raspberry Pi Zero2, 3, 4, and 5, based on \u003chttps://github.com/nix-community/nixos-images\u003e. They have several advantages over the \"standard\" ones, making the installation more user-friendly: mDNS enabled, `iwd` for easier wlan configuration, etc.\n\nNote: these images are mutable, i.e. they're suitable to be used both as an installation media, and as a ready to use system on the sd-card. The partition table will be expanded to use all the available space during the first boot.\nThis can helpful for boards with a single storage device option, like RPi Zero/Zero 2.\n\n\u003e [!TIP]\n\u003e installer images use new generational bootloader for RPi5 by default (see #60),\n\u003e to keep that in your configuration, set `boot.loader.raspberry-pi.bootloader = \"kernel\"`.\n\u003e This is _recommended_ for new installations.\n\nSee `nixosConfigurations.rpi{02,4,5}-installer` in `flake.nix`.\n\nSD image can be built with:\n\n```\nnix build .#installerImages.rpi02\nnix build .#installerImages.rpi3\nnix build .#installerImages.rpi4\nnix build .#installerImages.rpi5\n```\n\nRandomly generated connection credentials will be displayed on the screen, once the system is booted.\n\nNetwork access to Raspberry Pi Zero2 (RPi02) boards is also possible via USB Gadget/Ethernet functionality.\n\n\u003e [!TIP]\n\u003e You can optionally replace `# YOUR SSH PUB KEY HERE #` in `custom-user-config`\n\u003e with your SSH public key to generate the image with your SSH key already baked in\n\n`.#nixosConfigurations.rpi{02,4,5}-installer.config.system.build.toplevel` are included in the binary cache.\n\n# NixOS configuration examples\n\nSophisticated demo configurations are available in \u003chttps://github.com/nvmd/nixos-raspberrypi-demo\u003e.\n\nInstaller configurations can also double as the configuration examples.\n\n# Deployment\n\nfor example, with `nixos-anywhere` to the system running installer image (will use [disko](https://github.com/nix-community/disko/) to set the disks up):\n\n```shell\nnixos-anywhere --flake .#\u003csystem\u003e root@\u003chostname\u003e\"\n```\n\nor, to an already running system (to change configuration of it):\n\n```shell\nnixos-rebuild switch --flake .#\u003csystem\u003e --target-host root@\u003chostname\u003e\n```\n\n# Alternative ways to get individual packages\n\nAn alternative ways to consume individual packages without overlays are:\n\n- to get it directly from the flake, it will based on stable `nixpkgs` _without_ any of other optimisations transitively applied (i.e. only this particular package is optimised):\n\n```nix\n  environment.systemPackages = [\n    nixos-raspberrypi.packages.aarch64-linux.vlc\n  ];\n```\n\n- to get it from `nixos-raspberrypi.legacyPackages.\u003csystem\u003e`. Here all overlays are applied.\n\n# Design goals\n\nThis is basically [`boot.loader.raspberryPi` options](https://search.nixos.org/options?channel=unstable\u0026show=boot.loader.raspberryPi), which are deprecated in nixpkgs, but updated and improved upon.\n\nDesign objectives:\n\n- individually consumable modules and overlays for specific functions\n- reuse of the existing nixos/nixpkgs infrastructure and idiomatic approaches to the maximum extent possible\n- integration with the existing nixos system activation\n\n## Historical background\n\nThis project grew naturally out of the need to configure and extend rather great [tstat's raspberry pi support repository](https://github.com/tstat/raspberry-pi-nix), which we used for some time.\n\nUnfortunately it was virtually impossible to work with it without reengineering the whole thing, so this Flake was born. Inability to use it non-interactively with `nixos-anywhere` was the biggest concern.\n\nWe found [`boot.loader.raspberryPi` options](https://search.nixos.org/options?channel=unstable\u0026show=boot.loader.raspberryPi) to be much more idiomatic, easier to extend, and maintain.\n\nThis flake strives to keep and improve those properties by keeping it as unopinionated as possible and modular (see [above](#design-goals))\n\nWe're still using some of the modules provided by an adapted fork of tstat/raspberry-pi-nix, namely `config.txt` generation module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvmd%2Fnixos-raspberrypi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvmd%2Fnixos-raspberrypi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvmd%2Fnixos-raspberrypi/lists"}