nix-alien: running an unpatched binary on NixOS with its libraries

The problem is a missing library, not a missing file

The introduction states the situation directly. You are running nix or NixOS and have ever encountered this:

$ ./myapp
bash: ./myapp: No such file or directory

The error message is misleading, because the file is there. What is missing is the shared library the binary was linked against, and on NixOS that library is not in the system profile because the system profile only contains what Nix put there. nix-alien is the answer to that: it downloads the necessary dependencies for you, so a binary you did not build can still run. The approach is the one Nix itself uses, with the packages being looked up rather than assumed, and the tool is written in Python with the repository topics being nix, nixos and nixpkgs. It is MIT licensed, the last push was on 2026-10-15, and there are no GitHub releases, so the source tree is what you would look at.

Three commands for three different situations

The tool exposes three commands and the difference between them is the mechanism, not the goal. nix-alien runs the binary inside an FHS shell with all the needed shared dependencies to execute it. nix-alien-ld spawns you inside a shell with NIX_LD_LIBRARY_PATH set to the needed dependencies, to be used with nix-ld. nix-alien-find-libs lists all the libraries needed for the binary. So the first is a self-contained wrapper, the second hands the work to the nix-ld loader, and the third does no running at all, it just reports. The nix-alien-ld route exists for people already using nix-ld, and it is worth knowing that the two paths cache their generated environments in different places, one under a fhs-env directory and the other under a nix-ld directory. The FHS approach is the more portable of the two because it does not depend on the nix-ld configuration being right, while the nix-ld approach is less invasive on the system.

Running it once, and the cache that makes the second run fast

Once nix-alien is installed, the usage is short. You run it against the binary:

$ nix-alien ~/myapp

This runs the binary with an FHSUserEnv including all the shared library dependencies, and the resulting default.nix file is saved under the cache directory at $XDG_CACHE_HOME/nix-alien/<path-uuid>/fhs-env/default.nix, which makes the next evaluation faster. The cache is keyed on the binary's absolute path, so a different binary gets a different entry. Two flags manage that file. The --recreate flag forces the recreation of default.nix, which you want after the libraries have changed, and --destination changes where the file is saved. Arguments to the application itself are passed after a double dash, so the wrapper can tell them apart from its own:

$ nix-alien ~/myapp -- --foo bar

The same shape applies to the other two commands, with nix-alien-ld taking the binary and then the arguments in the same way.

Finding the libraries on their own, for scripting

The third command is the one to reach for when you want to script around it. nix-alien-find-libs prints the found libraries on stdout, and the informational messages go to stderr, so you can redirect those to /dev/null and keep the library list clean for a pipeline. There is also a --json flag to print the result as JSON instead of a plain list. The README describes this as the fzf based menu to find the libraries for scripting purposes, and that phrase understates what the command is: what you actually have is a machine readable list of the shared libraries a binary depends on, which is the starting point for building a nix expression by hand for that program. The information messages going to stderr is the detail that makes it usable in a script, since it is what stops the human facing output from corrupting the machine facing one.

The command line options are mostly about the library search

The help output for nix-alien shows the whole surface, and it is a small one. There is a positional program to run and an ellipsis of arguments to be passed to it, and then the options that shape the dependency search. -l adds an additional library to search and may be passed multiple times, -p adds an additional package, and -c provides library candidates that will be auto-selected if found via a regex, which the help says is useful for automation. The rest are output controls: -r recreates the default.nix file if it exists, -d sets the path where it will be created, -P prints where the file is located and exits, -E edits it with your editor or nano if that is unset, -s silences the informational messages, and -f creates and uses a flake.nix file instead, which is marked experimental. The -c and -p options are the ones that matter when the automatic search picks the wrong library, which is the failure mode you will actually hit.

Running it without installing it

There is a way to run the scripts from the repository without cloning or installing them, assuming a reasonably up to date nix with experimental Flakes support. The commands name the script directly:

$ nix run "github:thiagokokada/nix-alien#nix-alien" -- ~/myapp
$ nix run "github:thiagokokada/nix-alien#nix-alien-ld" -- ~/myapp
$ nix run "github:thiagokokada/nix-alien#nix-alien-find-libs" -- ~/myapp

And if you do not have Flakes enabled but still want to run it without downloading it first, the same commands work with the experimental features flag passed explicitly:

$ nix --extra-experimental-features "nix-command flakes" run "github:thiagokokada/nix-alien#nix-alien" -- ~/myapp
$ nix --extra-experimental-features "nix-command flakes" run "github:thiagokokada/nix-alien#nix-alien-ld" -- ~/myapp
$ nix --extra-experimental-features "nix-command flakes" run "github:thiagokokada/nix-alien#nix-alien-find-libs" -- ~/myapp

The hash and the two dashes are both load bearing. The hash selects which of the three scripts in the repository you want, since the repository contains all three, and the double dash separates the arguments to nix from the arguments to your program.

Installing it as a NixOS package, and the Flakes caveat

For a NixOS machine, the readme gives a module to drop into the configuration. The package set is imported from a fetched tarball of the repository, and the module adds nix-alien to environment.systemPackages, with a comment marking the nix-ld enable as optional but needed for the nix-alien-ld command. You then add the file to the imports section of the configuration. The Flakes version does the same thing through a flake with a nixpkgs input and a nix-alien input, producing a nixosConfiguration that installs the package and optionally enables nix-ld. The warning attached to that route is specific and worth heeding: overriding the nix-alien inputs may cause mismatches between the nix-index-database and nixpkgs, causing possibly incorrect results, so it is unsupported. That sentence explains the whole design, because the tool's job is to look up a library in one index and find a matching package in the other, and those two have to agree for the answer to be right.

Editorial conclusion

nix-alien suits a NixOS user who has to run a binary that was not built for Nix, such as a vendor download or an OpenGL application, and who does not want to patch it. It does not suit someone who can rebuild the software as a Nix package, since that is the cleaner fix, and it does not remove the need for the tool to know where your libraries live. Before you rely on it, check that the library index it queries is present on your machine, and read the Flakes warning, because overriding the nix-alien inputs is explicitly unsupported.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. thiagokokada/nix-alien on GitHub