Introducing Modulon 🦾

A plug-and-play module management framework for NixOS flakes

Works with: NixOS • macOS (via Home Manager) • Generic GNU/Linux (via Home Manager)

---

Quick Start

1. Add the flake input:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    modulon = {
      url = "github:cig0/modulon";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { modulon, nixpkgs, self, ... }:
    # ... rest of your flake
}

2. Use the library function:

let
  system = "x86_64-linux";
  moduleImporter = modulon.lib.${system};
in {
  nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
    inherit system;
    modules = [
      ./configuration.nix
      (moduleImporter { dirs = [ ./modules ]; })
    ];
  };
}

That's it! Modulon will automatically discover and import all valid NixOS modules from ./modules.

---

Table of Contents

• Quick Start
• Documentation
  • How It Works — Module discovery process and pattern matching
  • Configuration — Options reference and defaults
  • Excluding Modules — excludePaths, @MODULON_SKIP tag
  • Extra Modules — Including specific modules from excluded paths
  • Testing — Running and debugging flake checks
  • Contributing — How to contribute
• License

---

License

Unless otherwise stated, everything in this repo is covered by the following copyright notice:

Automatic NixOS Module Importer.
Copyright (C) 2024-2026  Martín Cigorraga <cig0.github@gmail.com>

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License v3 or later, as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.