How do users find the right options/attributes?

Hi. I am unfortunately in the middle of my third or fourth failure to get over the Nixos learning curve. I learned the expression language and have read through the manual’s explanation of Nixos’ architecture. Can anyone help me understand how users deal with discoverabiliity in nixpkgs/configuration options?

For example, I’m running Nixos in Virtualbox with i3 and need to change the size of the display. To determine it wasn’t a Virtualbox problem, I changed it manually via xrandr on the Nixos guest and it worked fine. I could do this on boot with a separate script, but being Nixos, I figured there must be an option to tell xrandr to do this via configuration.nix. After some searching, I discover that there are options services.xserver.xrandrHeads.*.monitorConfig and services.xserver.virtualDisplay. The latter doesn’t seem to help, and the former is essentially unstructured text, so I try emulating some of the inputs in the nix expression, like DisplaySize X Y to no avail. It does however tell me I can find configuration options in xorg.conf, though I don’t know what that is. I do some more searching and find some old-ish posts saying Nixos places anxorg.conf file at /etc/X11. I discover that this file does not exist on my machine, nor can I locate it with find. After some guess-work with the xrandrHeads and virtualScreen options, I still have a display that is not the correct size.

What could I have done differently? Where should I have looked for reference information (I used mostly the nixpkgs github and the search options/packages functions on

Thank you for any help.

1 Like

I usually search the options page at

There is also an auto complete package for emacs, I believe.

1 Like

My suggestion is to first read all the options descriptions. Perhaps skip services.* entirely, as this is very service specific. But everything else should be read, just to know it exists.

Next is grep -r or rg or ag on the nixos/ subdirectory of nixpkgs repo. If you know how something should be implemented, you can lookup by implementation and figure out, which modules do define corresponding options.

And finally, do read some existing configurations. Configuration Collection - NixOS Wiki, though I’d wish each config should have a little description what is inside. For example, @kampfschlaefer’s nixconfigs are a good source for thought about power of declarative containers wrt networking

1 Like

If you’re an emacs helm user, the helm-nixos-options function is very useful:

Basically, it gives you fuzzy auto-completion of all nixos options in an interactive buffer, and selecting one brings up the documentation for that option.

There’s also a cmdline equivalent, nixos-option, which doesn’t give the same interactive feedback, but is something you could pipe through fzf or fpp perhaps to stitch together a similar workflow.

Failing that, rg on the git repo always finds what you’re looking for sooner or later.

1 Like

My cmdline-centric approach:

  • when searching for packages I try nix search foo first
  • for NixOS options there’s man configuration.nix (and search by typing /foo)
  • if either fails the next step is to grep (ag/rg/ack) local clone of nixpkgs repo (find | grep foo to search for filenames)
1 Like