DEV Community

Cover image for How I Packaged a .deb File for NixOS with Flakes
oxcl
oxcl

Posted on

How I Packaged a .deb File for NixOS with Flakes

#linux #tutorial #opensource #showdev

I wanted to run Helium browser on NixOS. Helium only publishes .deb packages on GitHub releases. no AUR, no Nix package, nothing. So I packaged it myself.

https://github.com/oxcl/nix-flake-helium-browser

The same technique works for any app that ships a .deb but has no Nix package. This covers the full process: grabbing the .deb from a GitHub release, unpacking it, patching the binaries so they run on NixOS, putting it all in a flake, and then writing a NixOS module and a Home Manager module on top. Helium is just the example. the pattern applies to any pre-built binary.

Why NixOS can't just run a .deb

On a normal Linux distro, apt install ./thing.deb copies files into /usr/lib, /usr/bin, etc. The binaries look for shared libraries at those hardcoded paths.

NixOS doesn't have /usr/lib. Libraries live under /nix/store/some-hash-name/lib. A binary compiled on Ubuntu will try to load libc.so.6 from a path that simply doesn't exist on NixOS — it crashes before it does anything.

The fix is patchelf. It rewrites the ELF headers of a binary to point to the actual library paths in the Nix store. That's the whole trick. The nixpkgs wiki on packaging binaries is worth reading before you start.

Step 1: Declare the source with fetchurl

Find the .deb download URL from the project's GitHub releases page. In Nix, you don't download things with curl at build time — you declare the source with fetchurl, which also verifies a hash so the build is reproducible:

let
  pname   = "myapp";
  version = "1.2.3";
in

src = fetchurl {
  url    = "https://github.com/someorg/myapp/releases/download/${version}/myapp_${version}_amd64.deb";
  sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
};
Enter fullscreen mode Exit fullscreen mode

To get the hash, run:

nix-prefetch-url --type sha256 'https://github.com/someorg/myapp/releases/download/1.2.3/myapp_1.2.3_amd64.deb'
Enter fullscreen mode Exit fullscreen mode

Then convert it to SRI format:

nix hash to-sri --type sha256 <hash from above>
Enter fullscreen mode Exit fullscreen mode

If the project publishes both amd64 and arm64 builds, you can select the right one based on the target platform:

suffix = {
  aarch64-linux = "arm64";
  x86_64-linux  = "amd64";
}.${stdenv.hostPlatform.system} or (throw "Unsupported system: ${stdenv.hostPlatform.system}");
Enter fullscreen mode Exit fullscreen mode

Step 2: Unpack the .deb

A .deb file is an ar archive. Inside it you'll find data.tar.xz (the actual files) and control.tar.xz (package metadata). You only need the data. In stdenv.mkDerivation, override unpackPhase:

unpackPhase = ''
  runHook preUnpack

  ar vx $src
  tar -xvf data.tar.xz

  runHook postUnpack
'';
Enter fullscreen mode Exit fullscreen mode

After this, you'll have the directory structure from the .deb in your build directory — things like usr/bin/myapp, usr/share/applications/myapp.desktop, and so on.

You need binutils (which provides ar) in nativeBuildInputs:

nativeBuildInputs = [ patchelf makeWrapper binutils ];
Enter fullscreen mode Exit fullscreen mode

nativeBuildInputs is for tools that run during the build. buildInputs is for libraries the package links against at runtime. Mixing them up breaks cross-compilation.

Step 3: Copy files and patch the binaries

The install phase copies files out of the unpacked .deb into $out (your package's Nix store path), then patches the binaries so they can actually run.

installPhase = ''
  runHook preInstall

  mkdir -p $out/bin $out/share

  # Copy the binary and shared assets
  cp usr/bin/myapp $out/bin/myapp
  cp -r usr/share  $out/share

  # Patch the binary to use the Nix linker and library paths
  patchelf \
    --set-interpreter "$(cat $NIX_CC/nix-support/dynamic-linker)" \
    --set-rpath "${libPath}" \
    $out/bin/myapp

  # Fix absolute paths in the .desktop file
  substituteInPlace $out/share/applications/myapp.desktop \
    --replace-fail 'Exec=myapp' "Exec=$out/bin/myapp"

  runHook postInstall
'';
Enter fullscreen mode Exit fullscreen mode

--set-interpreter rewrites which dynamic linker the binary uses. On Ubuntu this is something like /lib64/ld-linux-x86-64.so.2, which doesn't exist on NixOS. $(cat $NIX_CC/nix-support/dynamic-linker) gives you the correct one from the Nix store.

--set-rpath rewrites where the binary looks for shared libraries at runtime. The libPath variable is built from your dependency list:

deps    = [ zlib glib dbus /* whatever your app actually needs */ ];
libPath = lib.makeLibraryPath deps;
Enter fullscreen mode Exit fullscreen mode

If you're not sure what your app needs, run it on a normal Linux distro with:

LD_DEBUG=libs ./myapp 2>&1 | grep "not found"
Enter fullscreen mode Exit fullscreen mode

That lists exactly what's missing. Add those to deps and repeat until the app starts.

For a real-world example with a complex dependency list (Chromium-based apps need a lot), see helium.nix.

A note on wrapGAppsHook

If you're packaging a GTK app, replace makeWrapper in nativeBuildInputs with wrapGAppsHook3. It handles GSettings schemas, icon themes, and other GTK machinery automatically. You then inject extra flags in preFixup rather than calling wrapProgram manually:

preFixup = ''
  gappsWrapperArgs+=(
    --prefix LD_LIBRARY_PATH : "${libPath}"
  )
'';
Enter fullscreen mode Exit fullscreen mode

For non-GTK apps, makeWrapper with a plain wrapProgram call is enough. See the wrapGAppsHook documentation for the full picture.

Step 4: The package file and the flake

Put the derivation in its own file — myapp.nix. The flake.nix wires everything together:

{
  description = "My app flake";

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

  outputs = { self, nixpkgs }:
    let
      supportedSystems = [ "x86_64-linux" "aarch64-linux" ];
      forAllSystems     = nixpkgs.lib.genAttrs supportedSystems;
    in
    {
      packages = forAllSystems (system:
        let pkgs = nixpkgs.legacyPackages.${system}; in
        {
          myapp   = pkgs.callPackage ./myapp.nix {};
          default = self.packages.${system}.myapp;
        }
      );

      apps = forAllSystems (system: {
        default = {
          type    = "app";
          program = "${self.packages.${system}.myapp}/bin/myapp";
        };
      });

      overlays.default     = final: prev: { myapp = final.callPackage ./myapp.nix {}; };
      nixosModules.default = import ./modules/nixos;
      homeModules.default  = import ./modules/home-manager;
    };
}
Enter fullscreen mode Exit fullscreen mode

forAllSystems runs the function for each supported system and collects the results. pkgs.callPackage injects arguments into myapp.nix automatically by matching parameter names against packages in pkgs.

Once this is in place, anyone can run your app with nix run github:you/myapp-flake without installing anything. For flake basics, the NixOS wiki on flakes is the best starting point.

Step 5: The NixOS Module

A NixOS module lets users configure your package declaratively in their configuration.nix. Every module has the same basic shape:

{ config, lib, pkgs, ... }:

{
  options = { /* declare options */ };
  config  = { /* apply them when enabled */ };
}
Enter fullscreen mode Exit fullscreen mode

A minimal one for any app:

{ config, lib, pkgs, ... }:

let cfg = config.programs.myapp; in

{
  options.programs.myapp = {
    enable = lib.mkEnableOption "myapp";

    package = lib.mkOption {
      type    = lib.types.package;
      default = pkgs.myapp;
    };

    flags = lib.mkOption {
      type        = lib.types.listOf lib.types.str;
      default     = [];
      description = "Extra command-line flags to pass at launch.";
    };
  };

  config = lib.mkIf cfg.enable {
    environment.systemPackages = [
      (cfg.package.override { flags = cfg.flags; })
    ];
  };
}
Enter fullscreen mode Exit fullscreen mode

lib.mkIf means nothing fires unless enable = true. The flags option passes down to the package derivation via .override, and the wrapper script bakes them in — so the binary in $PATH always runs with those flags appended.

To use the module, users add your flake as an input:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    myapp.url   = "github:you/myapp-flake";
    myapp.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, myapp, ... }: {
    nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
      system  = "x86_64-linux";
      modules = [
        myapp.nixosModules.default
        ({ nixpkgs.overlays = [ myapp.overlays.default ]; })
        ./configuration.nix
      ];
    };
  };
}
Enter fullscreen mode Exit fullscreen mode

Then in configuration.nix:

programs.myapp = {
  enable = true;
  flags  = [ "--some-flag" ];
};
Enter fullscreen mode Exit fullscreen mode

The NixOS module system documentation covers the full options/config API — the official docs are actually good here.

Step 6: The Home Manager Module

Structurally identical to the NixOS module, but scoped to a single user. The config block writes to user-level paths instead of system ones:

config = lib.mkIf cfg.enable {
  home.packages = [
    (cfg.package.override { flags = cfg.flags; })
  ];
};
Enter fullscreen mode Exit fullscreen mode

To use it:

{
  inputs = {
    nixpkgs.url      = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    myapp.url        = "github:you/myapp-flake";
  };

  outputs = { nixpkgs, home-manager, myapp, ... }: {
    homeConfigurations."youruser" = home-manager.lib.homeManagerConfiguration {
      pkgs    = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        myapp.homeModules.default
        ./home.nix
      ];
    };
  };
}
Enter fullscreen mode Exit fullscreen mode

Then in home.nix:

programs.myapp = {
  enable = true;
  flags  = [ "--start-maximized" ];
};
Enter fullscreen mode Exit fullscreen mode

The Home Manager manual covers everything. If you already understand the NixOS module system, this one is the same pattern.

Testing 

# Build
nix build .#myapp

# Run it
./result/bin/myapp

# See what the wrapper script actually does
cat result/bin/myapp

# Check what the binary links against
ldd result/bin/myapp
Enter fullscreen mode Exit fullscreen mode

If ldd shows => not found, add those libraries to deps and rebuild. That loop — build, ldd, add dep, repeat — is most of the real work when packaging pre-built binaries. It's not glamorous, but it's finite.

For real-world reference, the nixpkgs packages for Vivaldi and Brave use this same .deb-extraction pattern. Comparing against those when something isn't working is usually faster than reading docs.

One thing worth adding from day one

The version and SHA256 are hardcoded in the package file. When the app releases a new version, those values need manual updates. A GitHub Actions workflow that checks for new releases on a schedule and opens a PR when something changes is worth setting up early — otherwise the package goes stale and you forget about it for months.

The full example: Helium Browser

This entire post came from wanting to use Helium on NixOS — a private, Chromium-based browser that ships with uBlock Origin built in and no Google account integration. It's a solid daily driver if you want a clean browser without an afternoon of extension configuration.

The flake that packages it has everything covered in this post, plus multi-arch support, Wayland detection, a Chromium policy system in the NixOS module, and a GitHub Actions auto-update workflow. If you use NixOS and want a browser that's already packaged up with declarative config support, give it a try.

github.com/oxcl/nix-flake-helium-browser

If it's useful to you, a ⭐ on the repo is appreciated. And if you end up packaging something with this pattern and run into issues, pull requests are open.

Resources

Top comments (0)