How I Packaged a .deb File for NixOS with Flakes

oxcl — Thu, 07 May 2026 12:19:34 +0000

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=";
};

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'

Then convert it to SRI format:

nix hash to-sri --type sha256 <hash from above>

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}");

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
'';

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 ];

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
'';

--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;

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"

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}"
  )
'';

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;
    };
}

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 */ };
}

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; })
    ];
  };
}

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
      ];
    };
  };
}

Then in configuration.nix:

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

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; })
  ];
};

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
      ];
    };
  };
}

Then in home.nix:

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

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

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

NixOS wiki: Packaging Binaries — start here
NixOS wiki: Flakes — flake basics and setup
nix.dev: Flake concepts — the output schema reference
NixOS module system — writing your own modules
nixpkgs overlays — how overlays work
Home Manager manual — everything home-manager
wrapGAppsHook documentation — for GTK apps specifically
helium.nix — full real-world derivation for a complex app
Vivaldi nixpkgs package — .deb repackaging reference
Brave nixpkgs package — same pattern, different app

What If Money Is Time? A Wild Take on Economical Relativity

oxcl — Sat, 29 Mar 2025 10:05:21 +0000

You’ve heard “time is money” a million times. But what if we flip it? What if money — GDP, cash flow, economic juice — is actually time? Not the ticking-clock kind, but the way societies move through history. The faster your economy grows, the quicker you blast into the future. The slower it crawls — or collapses — the more you’re stuck in the past. I call it economical relativity, and it’s been rattling around my brain lately. Let me break it down.

Think about North Korea and South Korea. Same people, same language, split by a border. North Korea’s GDP per person is barely $1,700 — most folks don’t have internet, electricity’s a gamble, and food’s a daily hustle. It’s like living in the 1800s, scraping by with no window to the world. Then there’s South Korea — $34,000 per head, high-speed everything, skyscrapers, K-pop. They’re not just richer; they’re in a different era. Money didn’t just buy stuff — it sped up their societal clock while North Korea’s stayed frozen.

History’s full of this. Way back, fire was the first big win. It cooked food, kept us warm, let us craft better tools — boom, prehistoric GDP spiked, and human life leaped forward. Bows and arrows? Same deal — hunting got easier, food piled up, tribes grew. Fast-forward to steam engines: factories popped up, cities exploded, and the industrial age rewrote time in decades, not centuries. Each technological advancement pumped the economy, and with it, society raced ahead.

Now look at Poland. A hundred years ago, they were dirt poor, barely scraping by — like North Korea today. But since the ’90s, their GDP’s soared over tenfold. They didn’t just catch up; they hit fast-forward, building a modern world while the US, already comfy, just coasted. For Poland, those decades felt like centuries of progress crammed into a sprint. Meanwhile, Venezuela’s a grim flip-side. Their GDP’s crashed 75% since 2013 — now it’s bartering, blackouts, and breadlines. It’s not just a crisis; it’s like 1920 rolled back in.

Here’s the kicker: tech’s the engine, and AI’s the next beast. Countries jumping on artificial intelligence could turbocharge their economies — think healthcare breakthroughs, automated factories, smarter cities. Decades of progress might hit in a handful of years. South Korea’s already leaning in, while others sleep on it. The gap’s growing — not just in wealth, but in time. One nation’s living in 2040, another’s stuck in 2020. Adoption’s the catch, though — no investment, no skills, no infrastructure? You’re left behind, clock ticking slow.

So, economical relativity isn’t some abstract theory. It’s how money bends our sense of history. GDP growth doesn’t just pile up cash — it compresses time, shoving societies into the future. Stagnation or collapse? Time stretches, dragging you back to a world your ancestors might recognize. From fire to AI, technological advancement’s been the spark, lighting up economies and rewinding or fast-forwarding the human story.

Next time you hear about GDP stats, don’t yawn. It’s not just numbers — it’s a time machine. Poland’s sprinting, Venezuela’s rewinding, and AI’s about to hit the gas. Money isn’t just power; it’s how fast we live.

DEV Community: oxcl