nix-portable: Rootless Nix Without System Installation

Why nix-portable Exists for Restricted Linux Hosts

nix-portable addresses a specific gap between ordinary Nix installations and fully provisioned NixOS systems. The README presents it as rootless and configuration free, with the package description emphasizing a static, permissionless, installation-free build. That makes it relevant to engineers working on locked-down workstations, minimal containers, CI images, borrowed machines, or Linux distributions that do not provide a convenient system-level Nix package.

The executable removes several common setup steps. It arrives as one file, preconfigures a nixpkgs channel, enables the `flakes` and `nix-command` features, and carries the Nix components needed to run Nix commands. The host does not need a persistent profile update or a system package manager operation. Commands can be passed directly to the executable, or a symlink can make the portable binary behave like a native Nix subcommand.

This is not a general-purpose portable application format for every kind of software. Bundling requires the selected software to already be packaged for Nix. The intended audience is therefore engineers who already accept Nix's package model and need its command-line environment on hosts where installing Nix conventionally would be inconvenient or prohibited.

How nix-portable Virtualizes the Nix Store

The core mechanism is a self-extracting archive that caches its contents under `$HOME/.nix-portable`. Nix normally expects packages in `/nix/store`. nix-portable instead virtualizes that directory so its actual store resides at `$HOME/.nix-portable/store`. The repository description and topics associate the project with namespaces, `bubblewrap`, `proot`, and Nix, which correspond to the isolation mechanisms documented under the hood.

The runtime preference order is explicit. nix-portable first tries the Nix implementation shipped with the executable, then an existing `bwrap`, then its bundled `bwrap`, then an existing `proot`, and finally its bundled `proot`. It selects one automatically, although `NP_RUNTIME` can force `nix`, `bwrap`, or `proot`. This fallback chain is the central portability feature: the same download can work across different Linux environments without assuming that `bwrap` is installed.

The virtualized store also creates the project's main integration boundary. Software acquired outside nix-portable cannot directly link against or call programs obtained through it because the Nix store path exposed inside the virtualized environment is not the host filesystem's normal `/nix/store`. This is more consequential than a small PATH difference. A bundled interpreter and host-native extension, or a portable program calling an unrelated host library, may fall outside the portable package closure.

For developers, `NP_DEBUG=1` enables diagnostic messages, while `NP_DEBUG=2` enables shell tracing for `nix-portable`. Runtime and executable paths can also be overridden with `NP_NIX`, `NP_BWRAP`, `NP_PROOT`, and `NP_RUN`. These controls matter when automatic selection fails on a particular kernel or distribution.

Downloading nix-portable and Running the First Command

The README directs users to the GitHub releases page and provides a download command that selects an asset using the machine architecture. This writes the downloaded executable to the current directory as `nix-portable`.

curl -L https://github.com/DavHau/nix-portable/releases/latest/download/nix-portable-$(uname -m) > ./nix-portable

After the transfer completes, make the file executable. No root operation or host installation step is documented.

chmod +x ./nix-portable

A first safe check is the built-in help output for `nix-shell`. Passing arguments through the portable executable invokes Nix without changing the host's package configuration.

./nix-portable nix-shell --help

The expected result is the help text for `nix-shell`. If a more familiar command name is useful, the README documents a symlink named `nix-shell`. Because the underlying executable detects the invoked name, the symlink can stand in for that native executable.

ln -s ./nix-portable ./nix-shell

The same method is documented for other native Nix executables. The symlink is a local convenience, not a system-wide installation into a directory such as `/usr/bin`.

Running nixpkgs Programs Through the Portable Executable

The first real package-management operation can use `nix run` against `nixpkgs`. The README links readers to `search.nixos.org` for finding package attributes before constructing the command.

./nix-portable nix run nixpkgs#htop

This requests `htop` from the configured nixpkgs channel. The portable wrapper must first extract or access its bundled Nix components, and Nix must resolve the package and its dependencies. The README does not document a progress format or an exact cache size, so readers should not expect either to remain constant across versions.

For several programs at once, `nix shell` opens a temporary environment containing the named package set.

./nix-portable nix shell nixpkgs#{htop,vim}

Inside that shell, program names can be invoked directly. For example, after entering the temporary environment, this starts `htop`.

htop

This approach is appropriate for trying a package or creating an ephemeral command environment. It does not teach the host to expose the packages as normal system applications. Because the store is virtualized, host software also cannot assume that a binary in that store is available through the host's ordinary `/nix/store`.

Bundling Portable Executables with nix bundle

The bundling feature turns a Nix package or development environment into a self-contained executable intended to run on another supported Linux system. This is useful when one host has access to Nix and another host should receive a prepared closure without a conventional Nix installation.

For `hello`, the README invokes `nix bundle` with the `nix-portable` bundler. It then copies the generated executable from `bundle/bin/hello`, removes write permission, and runs it.

nix bundle --bundler github:DavHau/nix-portable -o bundle nixpkgs#hello

cp ./bundle/bin/hello ./hello && chmod +w hello

./hello

The documented output is `Hello World!`. The prerequisite is that the target software is already represented as a Nix package. This makes bundling a packaging operation, not a generic converter for arbitrary binaries.

Python illustrates why a closure can be useful. The documented expression attaches `numpy`, `scipy`, and `pandas` to Python, bundles the result, and copies the `python3` executable.

nix bundle --bundler github:DavHau/nix-portable -o bundle --impure --expr \
  '(import <nixpkgs> {}).python3.withPackages (ps: [ ps.numpy ps.scipy ps.pandas ])'

cp ./bundle/bin/python3 ./python3 && chmod +w ./python3

./python3 -c 'import numpy, scipy, pandas; print("Success !")'

The README states that this prints `Success !`. For smaller bundles, it directs builders to the `#zstd-max` bundler variant. Whole `devShell` environments require a flake-based repository and `numtide/devshell`; the README explicitly says a nixpkgs `mkShell` will not work because it is not executable.

A real alternative is installing Nix conventionally with the system package manager and managing that installation there. nix-portable changes the delivery boundary: it favors a single portable artifact and rootless operation, while conventional installation offers ordinary host filesystem visibility and avoids the virtualized-store interoperability limit.

Platform Boundaries, Missing Features, and Upgrade Cost

The stated platform target is Linux with an `x86_64` or `aarch64` CPU. The README says nix-portable is tested continuously on Arch Linux, Fedora, Debian, NixOS, and Ubuntu for `x86_64`, on Debian and NixOS for `aarch64`, and in GitHub Actions. The word "potentially" in the support statement matters: the architecture list is broader than the tested distribution list, but the README does not claim every Linux combination.

User namespaces are another boundary. If they are unavailable, nix-portable falls back to `proot`. The README warns that `proot` can introduce significant performance overhead depending on the workload. For expensive derivation work, it suggests using a remote builder or building on another host and synchronizing through a cache such as `cachix.org`. This makes nix-portable the wrong tool for a constrained host where isolation works only through the slowest documented mechanism.

The README explicitly lists missing features: `nix-env` profile management, `nix-channel` channel management, and macOS support. Administrators should not treat nix-portable as a drop-in replacement for a conventional multi-user Nix installation. It also does not provide a documented rollback procedure for changing `NP_RUNTIME` or moving `$HOME/.nix-portable`, and it does not define a cache-cleanup command in the supplied documentation.

Maintenance activity is supported by repository metadata: the project is not archived, and its last push was on 2026-10-15. The listed release history is older, with `v012` dated 2024-04-15, `v011` dated 2024-04-11, and `v010` dated 2023-10-16. That does not establish a release cadence or compatibility guarantee for host changes.

The project uses the MIT license. That permits broad use, modification, distribution, and sublicensing under the license's conditions, but operators still need to account for the separate licenses of Nix packages and bundled software. The README does not provide legal guidance about those dependencies. Upgrades can change the bundled Nix components, runtime behavior, or required package expressions, so existing bundles and environment definitions should be checked after moving to a newer release.

Editorial conclusion

Adopt nix-portable when root access, host configuration, and portability matter more than native integration. Do not choose it when applications must interoperate with host-installed software or when proot overhead is unacceptable. Verify runtime selection, cache placement, network access to Nix channels, and application compatibility on each target Linux distribution before relying on it for production workflows.

Frequently asked questions

Official sources

1. DavHau/nix-portable on GitHub
2. Issues
3. License: MIT
4. README
5. Releases