{"id":13441512,"url":"https://github.com/numtide/system-manager","last_synced_at":"2026-01-06T19:16:54.044Z","repository":{"id":152233629,"uuid":"617562687","full_name":"numtide/system-manager","owner":"numtide","description":"Manage system config using nix on any distro","archived":false,"fork":false,"pushed_at":"2025-04-01T22:03:47.000Z","size":673,"stargazers_count":960,"open_issues_count":39,"forks_count":29,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-06T19:02:24.268Z","etag":null,"topics":["buildbot-numtide","nix","nix-modules"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/numtide.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}},"created_at":"2023-03-22T16:38:41.000Z","updated_at":"2025-04-05T13:41:54.000Z","dependencies_parsed_at":"2023-11-10T21:27:46.722Z","dependency_job_id":"a006508b-c0ca-4de7-a522-abeee01063f3","html_url":"https://github.com/numtide/system-manager","commit_stats":{"total_commits":454,"total_committers":16,"mean_commits":28.375,"dds":0.6079295154185023,"last_synced_commit":"c9e35e9b7d698533a32c7e34dfdb906e1e0b7d0a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fsystem-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fsystem-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fsystem-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fsystem-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numtide","download_url":"https://codeload.github.com/numtide/system-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248784167,"owners_count":21161069,"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","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":["buildbot-numtide","nix","nix-modules"],"created_at":"2024-07-31T03:01:34.929Z","updated_at":"2026-01-06T19:16:54.039Z","avatar_url":"https://github.com/numtide.png","language":"Rust","funding_links":[],"categories":["HarmonyOS","Rust","Overlays","Nix"],"sub_categories":["Windows Manager","Webinterface"],"readme":"# \u003cimg alt=\"System Manager\" src=\"https://banner.numtide.com/banner/numtide/system-manager.svg\"\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://github.com/numtide/system-manager/actions/workflows/update-flake-lock.yml\"\u003e\u003cimg src=\"https://github.com/numtide/system-manager/actions/workflows/update-flake-lock.yml/badge.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://app.element.io/#/room/#home:numtide.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Support-%23numtide-blue\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nSystem Manager is a tool to configure Linux machines. Unlike Chef, Puppet and Ansible, it only controls a small subset, and most of its changes are done in an immutable layer, thanks to the power of Nix.\n\nUsing NixOS-style declarative configurations, you describe what your system should look like, by specifying packages, services, and settings all in Nix, then apply it safely and atomically with a single command. Each change is reproducible, just like NixOS generations.\n\nYou don't need to be an expert in Nix to use it, as its syntax is straightforward. But if you're familiar with Nix and Home Manager, think of System Manager as being similar, but for your entire machine. Whereas Home Manager manages user environments, System Manager manages the entire system, starting at root-level configurations, packages, and services, using the same reliable, Nix-based model.\n\nSystem Manager builds on the many modules that already exist in [NixOS].\n\n## Quick Example to Get Started\n\nWe will assume you're using a non-NixOS distribution (such as Ubuntu) and you have Nix already installed, with flakes enabled.\n\nSystem Manager has an \"init\" subcommand that can build a set of starting files for you. By default, it places the files in `~/.config/system-manager`. You can run this init subcommand by typing:\n\n```\nnix run 'github:numtide/system-manager' -- init\n```\n\nIf you see an error regarding experimental nix features, instead type the following:\n\n```\nnix run 'github:numtide/system-manager' --extra-experimental-features 'nix-command flakes' -- init\n```\n\n\u003e [!Tip]\n\u003e If you still have problems running this step, check out our full Getting Started guide, which includes how to handle issues of running as root, and whether you've installed Nix to be used by a single user.\n\n\u003e [!Note]\n\u003e You can optionally run the above under `sudo`, which will place the files under `/root/.config/system-manager`. You might need to pass the path, depending on how you installed Nix:\n\u003e `sudo env PATH=\"$PATH\" nix run 'github:numtide/system-manager' -- init`\n\nYou will now have two files under `~/.config/system-manager` (or `/root/.config/system-manager` if you ran the above under sudo):\n\n- flake.nix\n- system.nix\n\nGo ahead and switch to the folder:\n\n```\ncd ~/.config/system-manager\n```\n\n(Or to the root equivalent.)\n\nHere is what flake.nix looks like:\n\n```nix\n{\n  description = \"Standalone System Manager configuration\";\n\n  inputs = {\n    # Specify the source of System Manager and Nixpkgs.\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    system-manager = {\n      url = \"github:numtide/system-manager\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n\n  outputs =\n    {\n      self,\n      nixpkgs,\n      system-manager,\n      ...\n    }:\n    {\n      systemConfigs.default = system-manager.lib.makeSystemConfig {\n        # Specify your system configuration modules here, for example,\n        # the path to your system.nix.\n        modules = [ ./system.nix ];\n\n        # Optionally specify extraSpecialArgs and overlays\n      };\n    };\n}\n```\n\nFor these examples, we won't use the `system.nix` file; we'll create separate configuration files for each example.\n\nFind the following line in `flake.nix`:\n\n```\n        modules = [ ./system.nix ];\n```\n\nand change it to this:\n\n```\n        modules = [ ./cli_tools.nix ];\n```\n\nCreate a file in the same folder called `cli_tools.nix` and add the following into it:\n\n```nix\n{ pkgs, ... }:\n{\n  config = {\n    nixpkgs.hostPlatform = \"x86_64-linux\";\n    \n    environment.systemPackages = with pkgs; [\n      btop          # Beautiful system monitor\n      bat           # Modern 'cat' with syntax highlighting\n    ];\n  };\n}\n\n```\n\nThis specifies a configuration that includes `btop` and `bat` to be installed on the system. To do so, execute System Manager with the `--sudo` flag (assuming you have experimental features nix-command and flakes turned on):\n\n```\nnix run 'github:numtide/system-manager' -- switch --sudo --flake .\n```\n\nThe `--sudo` flag tells system-manager to use sudo for privileged operations (activating the configuration).\n\nAlso, note that you might need to enable `nix-commands` and `flakes` if you don't already have them set:\n\n```\nnix --extra-experimental-features 'nix-command flakes' run 'github:numtide/system-manager' -- switch --sudo --flake .\n```\n\n\u003e [!Note]\n\u003e The first time you run System Manager, it will update your path by adding an entry in the /etc/profile.d folder. For this change to take effect, you need to log out and then log back in. However, if you don't want to log out, you can source the file:\n\u003e `source /etc/profile.d/system-manager-path.sh`\n\nAnd now the two commands `btop` and `bat` should be available on your system:\n\n```\n$ btop --version\nbtop version: 1.4.5\nCompiled with: g++ (14.3.0)\nConfigured with: cmake -DBTOP_STATIC=OFF -DBTOP_GPU=ON\n$ bat --version\nbat 0.26.0\n```\n\nWant to remove a package? Simply remove it or comment it out in the `cli_tools.nix` file, and run it again. For example, if you want to remove `bat`, simply update the `default.nix` to the following:\n\n```nix\n{ pkgs, ... }:\n{\n  nixpkgs.hostPlatform = \"x86_64-linux\";\n  \n  environment.systemPackages = with pkgs; [\n    btop          # Beautiful system monitor\n    # bat         # Comment out or remove\n  ];\n}\n```\n\n## Regarding the Error\n\nYou might notice an error that looks like this:\n\n`[2025-11-17T15:06:46Z ERROR system_manager::activate::etc_files] Error while trying to link directory /etc/.system-manager-static/nix: Unmanaged path already exists in filesystem, please remove it and run system-manager again: /etc/nix/nix.conf`\n\nYou can safely ignore it; or, you can allow System Manager to take control of `nix.conf`. If you choose to have System Manager take control of `nix.conf`, rename `nix.conf` to a backup name, such as `nix_conf_backup`, and run System Manager again. Note, however, that if you had settings in your `nix.conf` file, they might not appear in the new file System Manager generates. For that read the following section, [Adding in Experimental Features](#adding-in-experimental-features).\n\n## Adding in Experimental Features\n\nIt's possible that you had a `nix.conf` file in `/etc/nix` that had experimental features set. And if you allowed System Manager to take control of that file, your setting will likely be gone. But that's okay; you now have control of your system right from the `flake.nix` file. You can add experimental features inside the modules list like so:\n\n```nix\n{\n  description = \"Standalone System Manager configuration\";\n\n  inputs = {\n    # Specify the source of System Manager and Nixpkgs.\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    system-manager = {\n      url = \"github:numtide/system-manager\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n\n  outputs =\n    {\n      self,\n      nixpkgs,\n      system-manager,\n      ...\n    }:\n    {\n      systemConfigs.default = system-manager.lib.makeSystemConfig {\n        # Specify your system configuration modules here, for example,\n        # the path to your system.nix.\n\t\n        modules = [\n            # Place additional settings here:\n            {\n                nix.settings.experimental-features = \"nix-command flakes\";\n            }\n            ./cli_tools.nix \n        ];\n\n        # Optionally specify extraSpecialArgs and overlays\n      };\n    };\n}\n```\n\nThen re-run System Manager and your changes will take effect; now you should have the two experimental features set, `nix-command` and `flakes`.\n\n# Full Installation and setup\n\n## Install Nix\n\nSystem manager itself does not need to be installed; but, you do need to install Nix. (However, you can optionally install system-manager locally if you prefer.)\n\nTo install Nix, you can either use your distro's package manager, or use one of the following available options to install Nix.\n\n- [Official Nix Installer][official-installer] - The canonical source for installing nix.\n- [Determinate Nix Installer][detsys-installer] - A wrapper around the official installer that has\n  SELinux support, and enables flake features by default.\n\n\u003e [!Tip]\n\u003e Some Nix users have had difficulty installing Nix on Windows Subsystem for Linux (WSL) using the official installer. If you're using WSL, we recommend using Determinate Nix installer.\n\n## Example: Configuring System Services\n\nThe following example demonstrates how to specify a system service and activate it.\n\nUpdate your flake.nix file to include a new file in the modules list, which we'll call `say_hello.nix`:\n\n```nix\n{\n  description = \"Standalone System Manager configuration\";\n\n  inputs = {\n    # Specify the source of System Manager and Nixpkgs.\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    system-manager = {\n      url = \"github:numtide/system-manager\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n\n  outputs =\n    {\n      self,\n      nixpkgs,\n      system-manager,\n      ...\n    }:\n    {\n      systemConfigs.default = system-manager.lib.makeSystemConfig {\n        # Specify your system configuration modules here, for example,\n        # the path to your system.nix.\n\t\n        modules = [\n            {\n                nix.settings.experimental-features = \"nix-command flakes\";\n            }\n            ./cli_tools.nix \n            ./say_hello.nix\n        ];\n\n        # Optionally specify extraSpecialArgs and overlays\n      };\n    };\n}\n\n```\n\nThen create the file called `say_hello.nix` and add the following to it:\n\n```nix\n{ lib, pkgs, ... }:\n{\n  config = {\n    nixpkgs.hostPlatform = \"x86_64-linux\";\n    \n    systemd.services.say-hello = {\n      description = \"say-hello\";\n      enable = true;\n      wantedBy = [ \"system-manager.target\" ];\n      serviceConfig = {\n        Type = \"oneshot\";\n        RemainAfterExit = true;\n      };\n      script = ''\n        ${lib.getBin pkgs.hello}/bin/hello\n      '';\n    };\n  };\n}\n```\n\nActivate it using the same nix command as earlier:\n\n```\nnix run 'github:numtide/system-manager' -- switch --sudo --flake .\n```\n\nThis will create a system service called `say-hello` (which comes from the line `config.systemd.services.say-hello`) in a unit file at `/etc/systemd/system/say-hello.service` with the following inside it:\n\n```\n[Unit]\nDescription=say-hello\n\n[Service]\nEnvironment=\"PATH=/nix/store/xs8scz9w9jp4hpqycx3n3bah5y07ymgj-coreutils-9.8/bin:/nix/store/qqvfnxa9jg71wp4hfg1l63r4m78iwvl9-findutils-4.10.0/bin:/nix/store/22r4s6lqhl43jkazn51f3c18qwk894g4-gnugrep-3.12/bin:\n/nix/store/zppkx0lkizglyqa9h26wf495qkllrjgy-gnused-4.9/bin:/nix/store/g48529av5z0vcsyl4d2wbh9kl58c7p73-systemd-minimal-258/bin:/nix/store/xs8scz9w9jp4hpqycx3n3bah5y07ymgj-coreutils-9.8/sbin:/nix/store/qqvfn\nxa9jg71wp4hfg1l63r4m78iwvl9-findutils-4.10.0/sbin:/nix/store/22r4s6lqhl43jkazn51f3c18qwk894g4-gnugrep-3.12/sbin:/nix/store/zppkx0lkizglyqa9h26wf495qkllrjgy-gnused-4.9/sbin:/nix/store/g48529av5z0vcsyl4d2wbh9\nkl58c7p73-systemd-minimal-258/sbin\"\nExecStart=/nix/store/d8rjglbhinylg8v6s780byaa60k6jpz1-unit-script-say-hello-start/bin/say-hello-start \nRemainAfterExit=true\nType=oneshot\n\n[Install]\nWantedBy=system-manager.target\n```\n\n\u003e [!Tip]\n\u003e Compare the lines in the `say-hello.service` file with the `say_hello.nix` file to see where each comes from.\n\nYou can verify that it ran by running journalctl:\n\n```\njournalctl -n 20\n```\n\nand you can find the following output in it:\n\n```\nNov 18 12:12:51 my-ubuntu systemd[1]: Starting say-hello.service - say-hello...\nNov 18 12:12:51 my-ubuntu say-hello-start[3488278]: Hello, world!\nNov 18 12:12:51 my-ubuntu systemd[1]: Finished say-hello.service - say-hello.\n```\n\n\u003e [!Note]\n\u003e If you remove the `./cli_tools.nix` line from the `flake.nix`, System Manager will see that the configuration changed and that `btop` and `bat` are no longer in the configuration. As such, it will uninstall them. This is normal and expected behavior.\n\n## Example: Creating files in the /etc folder\n\nOftentimes, when you're creating a system service, you need to create a configuration file in the `/etc` directory that accompanies the service. System manager allows you to do that as well.\n\nAdd another line to your `flake.nix` file, this time for `./sample_etc.nix`:\n\n```nix\n{\n  description = \"Standalone System Manager configuration\";\n\n  inputs = {\n    # Specify the source of System Manager and Nixpkgs.\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    system-manager = {\n      url = \"github:numtide/system-manager\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n\n  outputs =\n    {\n      self,\n      nixpkgs,\n      system-manager,\n      ...\n    }:\n    {\n      systemConfigs.default = system-manager.lib.makeSystemConfig {\n        # Specify your system configuration modules here, for example,\n        # the path to your system.nix.\n\t\n        modules = [\n            {\n                nix.settings.experimental-features = \"nix-command flakes\";\n            }\n            ./cli_tools.nix \n            ./say_hello.nix\n            ./sample_etc.nix\n        ];\n\n        # Optionally specify extraSpecialArgs and overlays\n      };\n    };\n}\n```\n\nThen, create the `sample_etc.nix` file with the following into it:\n\n```nix\n{ lib, pkgs, ... }:\n{\n  config = {\n    nixpkgs.hostPlatform = \"x86_64-linux\";\n    \n    environment.etc = {\n      sample_configuration = {\n        text = ''\n          This is some sample configuration text\n        '';\n      };\n    };\n  };\n}\n```\n\nRun it as usual, and you should see the file now exists:\n\n```\nnix run 'github:numtide/system-manager' -- switch --sudo --flake .\n\nls /etc -ltr\n```\n\nwhich displays the following:\n\n```\nlrwxrwxrwx  1 root  root  45 Nov 13 15:19 sample_configuration -\u003e ./.system-manager-static/sample_configuration\n```\n\nAnd you can view the file:\n\n```\ncat /etc/sample_configuration\n```\n\nwhich prints out:\n\n```\nThis is some sample configuration text\n```\n\n### Supported Systems\n\nSystem Manager is currently only supported on NixOS and Ubuntu. However, it can be used on other distributions by enabling the following:\n\n```nix\n{\n  config = {\n    system-manager.allowAnyDistro = true;\n  }\n}\n```\n\n\u003e [!WARNING]\n\u003e This is unsupported and untested. Use at your own risk.\n\n## Commercial support\n\nLooking for help or customization?\n\nGet in touch with Numtide to get a quote. We make it easy for companies to\nwork with Open Source projects: \u003chttps://numtide.com/contact\u003e\n\n[detsys-installer]: https://github.com/DeterminateSystems/nix-installer\n[nixos]: https://nixos.org\n[official-installer]: https://nixos.org/download.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Fsystem-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumtide%2Fsystem-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Fsystem-manager/lists"}