Skip to content

Running Downloaded Binaries on NixOS

Since NixOS does not strictly adhere to the Filesystem Hierarchy Standard (FHS), binaries downloaded from the internet may not work directly on NixOS. However, there are various methods available to make them function properly.

For a comprehensive guide that presents ten different approaches to run downloaded binaries on NixOS, I recommend reading the article Different methods to run a non-nixos executable on Nixos and take a look at nix-alien. Or if you are familiar with Docker, running the binary in a Docker container is also a good choice.

Among these methods, I personally prefer creating an FHS environment to run the binary, as it proves to be both convenient and easy to use. To set up such an environment, you can add the following code to one of your Nix modules:

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

  # ......omit many configurations

  environment.systemPackages = with pkgs; [
    # ......omit many packages

    # Create an FHS environment using the command `fhs`, enabling the execution of non-NixOS packages in NixOS!
    (let base = pkgs.appimageTools.defaultFhsEnvArgs; in
      pkgs.buildFHSUserEnv (base // {
      name = "fhs";
      targetPkgs = pkgs: (
        # pkgs.buildFHSUserEnv provides only a minimal FHS environment,
        # lacking many basic packages needed by most software.
        # Therefore, we need to add them manually.
        # pkgs.appimageTools provides basic packages required by most software.
        (base.targetPkgs pkgs) ++ with pkgs; [
          # Feel free to add more packages here if needed.
      profile = "export FHS=1";
      runScript = "bash";
      extraOutputsToInstall = ["dev"];

  # ......omit many configurations

After applying the updated configuration, you can use the fhs command to enter the FHS environment, and then execute the binary you downloaded, for example:

# Activating FHS drops me into a shell that resembles a "normal" Linux environment.
$ fhs
# Check what we have in /usr/bin.
(fhs) $ ls /usr/bin
# Try running a non-NixOS binary downloaded from the Internet.
(fhs) $ ./bin/code