| name | nix-packaging-best-practices |
| description | Best practices for packaging pre-compiled binaries (.deb, .rpm, .tar.gz, AppImage) for NixOS, handling library dependencies, or facing "library not found" errors with binary distributions |
| license | MIT |
| metadata | {"author":"chumeng","version":"1.0.0"} |
Packaging Binary Distributions for Nix
Extract and patch binary packages within Nix builds for reproducibility.
Core Principle
Source from original archive directly, never from pre-extracted directories.
When to Use
- Converting binary packages (.deb, .rpm, .tar.gz, .zip) to Nix derivations
- Packaging proprietary/closed-source software distributed as binaries
- Electron/GUI apps show "library not found" errors
- User provides pre-extracted binary contents
- Binary distributions need library path fixes
Don't use for:
- Software available in nixpkgs
- Source-based packages (use standard derivation)
- AppImages (use appimage-run or extract and patch)
Quick Reference
Essential Pattern (.deb)
{ pkgs }:
pkgs.stdenv.mkDerivation rec {
pname = "appname";
version = "1.0.0";
src = ./AppName-${version}-linux-amd64.deb;
nativeBuildInputs = with pkgs; [
autoPatchelfHook # Fixes library paths
dpkg # Extracts .deb
];
buildInputs = with pkgs; [
stdenv.cc.cc.lib
glib
gtk3
];
unpackPhase = ''
ar x $src
tar xf data.tar.xz
'';
installPhase = ''
mkdir -p $out
cp -r opt/AppName/* $out/
'';
}
Common Tasks
| Task | Solution |
|---|
| Local archive | src = ./package-${version}.tar.gz |
| Remote archive | src = fetchurl { url = "..."; hash = "sha256-..."; } |
| Extract .deb | ar x $src && tar xf data.tar.xz + dpkg |
| Extract .rpm | rpm2cpio $src | cpio -idmv + rpm, cpio |
| Extract .tar.gz | Auto-detected by stdenv |
| Extract .zip | Add unzip to nativeBuildInputs |
| Fix libraries | Add autoPatchelfHook to nativeBuildInputs |
| Find missing libs | Run ldd result/bin/app for "not found" |
| Quick test binary | nix-shell -p steam-run; steam-run ./binary |
| Debug autoPatchelf | nix log /nix/store/...-drv |
| Search libraries | nix-locate libX11.so.6 |
| Wrapper scripts | Add makeWrapper to nativeBuildInputs |
| Version sync | Use src = ./app-${version}.tar.gz |
Dependency Categories
nativeBuildInputs: Build-time tools (dpkg, autoPatchelfHook, makeWrapper)
buildInputs: Runtime libraries (gtk3, glib, libpulseaudio)
propagatedBuildInputs: Rarely needed for binary packaging
Common Library Mappings
| Missing Library | Nix Package |
|---|
libgtk-3.so.0 | gtk3 |
libglib-2.0.so.0 | glib |
libpulse.so.0 | libpulseaudio |
libGL.so.1 | mesa or libglvnd |
libxkbcommon.so.0 | libxkbcommon (NOT xorg.libxkbcommon) |
libstdc++.so.6 | stdenv.cc.cc.lib |
Red Flags - STOP
- "User already extracted it, use that directory" → NO, source from original archive
- "Absolute path works for me locally" → Breaks for others, use relative
- "Just add more libraries until it works" → Find actual dependencies with
ldd
How to Use
Read individual rule files for detailed explanations and code examples:
rules/essential-pattern.md
rules/archive-formats.md
rules/_sections.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
