PSA: Use nixos.org tarballs for your flake inputs!

A common pattern for nixpkgs flake inputs is to use a URL like github:nixos/nixpkgs/nixos-unstable. This isn’t the best choice! Instead, you should probably be using the official project-hosted channel tarballs from channels.nixos.org. Here are a few reasons why:

Reduced Download Sizes

The project tarballs use zstd compression, which is more efficient than Github’s gzip. By switching, your download sizes drop by 20%, completely free!

Forge Independence

Many have, justifiably, complained about the downsides of using GitHub as the project’s forge. While switching away from GitHub is still infeasible, you can help improve our ability to do so! By using the project tarballs, you uncouple your configuration from GitHub, making it easier for us to move away in the future.

Other Benefits

  • No issues with problematic and unstable GitHub rate-limiting.
  • Automatically-included database for command-not-found, which displays the package to pull for commands you don’t have installed.
  • IPv6 support for pulling tarballs.

How to Switch

Anywhere you have lines like this:

    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

Simply change it to this:

     nixpkgs.url = "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst";

Stable branches are supported too; simply change nixos-unstable to your preferred branch.

37 Likes

It would be nice if inputs had a comparably nice protocol shorthand for this so it looked like more of a proper idiom and didn’t require as much recall for new projects.

2 Likes

I am new to flakes

I have an input that looks like

nixpkgs.url = "nixpkgs/nixos-unstable"

and that resolves to

nixpkgs: https://releases.nixos.org/nixos/unstable/nixos-26.11pre1066703.0968519e14f7/nixexprs.tar.xz?narHash=sha256-gxryTzdoDQLrvPdYp8cSbxXpB/LDhaQhiJFCmkqVugw%3D (2026-09-03 03:08:44)

with nix flake metadata. I think it’s using the flake registry.

Yes, it is. Stop doing that! Indirect flake references in inputs can cause a number of subtle issues. They’re best just avoided. (In fact, multiple people have suggested they be disallowed by nix itself…)

1 Like

To date I have not found this documented in any proper formal place. It should probably be in the Nixpkgs manual and in the NixOS manual. I’m sure a PR would be welcome.

3 Likes

Nix path contexts can actually use channel:nixos-unstable directly:

it’s flakes that lack the quality-of-life for this scenario, oddly enough.

5 Likes

What are the issues that can come up?

Probably the most common one is failing to update at all because the registry pins nixpkgs to a specific commit, particularly if that pin is generated from a nixos config in the flake itself that pins to the flake inputs.

More generally, it’s just plain counter-intuitive that the behavior nix flake update is environment dependent.

2 Likes

…but nix flake update pinned my nixpkgs to a channel tarball. I am confused.

I can totally appreciate the arguments here

How do folks specify nixpkgs flakes at the command line without the registry?

I wasn’t suggesting it was happening in this case. It’s just the most common problem I’ve seen.

Using the registry from the command line is perfectly reasonable. I don’t think anyone is advocating against that. The problem is when you involve the registry in your flake.nix’s inputs section.

1 Like

It doesn’t help that nixos-generate-config --flake outputs a flake.nix with nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"

7 Likes

Thanks for pointing that out! I just put up a PR to change that:

I’m on a bit of a mission to change the defaults here to be better, so please keep pointing out areas where that’s still the recommended/default pattern.

10 Likes

TIL! That’s super handy. Too bad my stuff is drowning in flakes. :upside_down_face:

I was confused for a moment at the idea that pointing to an URL would cause issue when wanting to reproduce that build, but it turns out this URL redirect to a fixed input with some hash in it. I’m going to guess that the flake lock will pin that instead of the raw input URL. (I personally tend to use nixpkgs instead. Just a nice shorthand. It is true a way of pinning the flake registry itself as a flake input might be usefull. Thought that has not been a problem for me yet)

Also, looking at flake-registry/flake-registry.json at 10bd3d9e8eefb4725e346eddd3a505aa0aacf01b · NixOS/flake-registry · GitHub seems like those registry just redirect to the URL you mentionned.

It works through the Lockable HTTP Tarball Protocol, so yes, it will lock properly, just like a github or other commonly-used flake reference.

4 Likes

Does this interact well with the CLI flake update command? My current workflow is a weekly scripted update to the latest nixos-unstable which gets built by CI as PR against my infra repo. Although I haven’t had any issues with that workflow I’m always happy to move away from implementation details like being tied to GitHub directly.

Yep! Thanks to the protocol mentioned above, the tarballs are fully compatible with all of the normal commands you’d use with the CLI.

2 Likes