Skip to content


Repository files navigation


main built with nix

A tool that embosses the needed dependencies on the top level executable


It can be useful to freeze all the dynamic shared objects needed by an application.

shrinkwrap is a tool which will discover all transitive dynamic shared objects, and lift them up to the executable referenced by absolute path.

Here is an example where we will apply this to ruby.

Lets take a look at all the dynamic shared objects needed by the Ruby interpreter.

ldd $(which ruby) (0x00007ffeed386000)
	/lib/x86_64-linux-gnu/ (0x00007f638ddf8000) => /lib/x86_64-linux-gnu/ (0x00007f638da79000) => /lib/x86_64-linux-gnu/ (0x00007f638d8b4000) => /lib/x86_64-linux-gnu/ (0x00007f638d893000) => /lib/x86_64-linux-gnu/ (0x00007f638d888000) => /lib/x86_64-linux-gnu/ (0x00007f638d807000) => /lib/x86_64-linux-gnu/ (0x00007f638d7ff000) => /lib/x86_64-linux-gnu/ (0x00007f638d7c4000) => /lib/x86_64-linux-gnu/ (0x00007f638d67f000)
	/lib64/ (0x00007f638de06000)

We can see also that the ruby application only lists a few needed shared objects itself.

patchelf --print-needed $(which ruby)

Let's now apply shrinkwrap and see the results.

nix run github:fzakaria/shrinkwrap $(which ruby)

It automatically creates a _stamped copy of the filename if none provided and sets all the NEEDED sections.

patchelf --print-needed ruby_stamped
/lib/x86_64-linux-gnu/ ruby_stamped (0x00007ffe641f3000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd4320000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd41db000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd41a0000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd419a000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd4119000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd410e000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd40eb000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd3d8c000)
	/lib/x86_64-linux-gnu/ (0x00007f9cd3bc7000)
	/lib64/ (0x00007f9cd4336000)


Certain store based build tools such as Guix, Nix or Spack make heavy use of RUNPATH to help create reproducible and hermetic binaries.

One problem with the heavy use of RUNPATH, is that the search space could effect startup as it's O(n) on the number of entries (potentially worse if using RPATH). This can alo be expensive in stat syscalls, that has been well documented by in this blog post.

Secondly, shared dynamic objects may be found due to the fact that they are cached during the linking stage. Meaning, if another shared object requires the same dependency but failed to specify where to find it, it may still properly resolved if discovered earlier in the linking process. This is extremely error prone and changing any of the executable's dependencies can change the link order and potentially cause the binary to no longer work.

Lifting up the needed shared objects to the top executable makes the dependency discovery simple, quick and hermetic since it can no longer change based on the order of visited dependencies.


At the moment this only works with glibc and not other Standard C Libraries such as musl. The reason is that other linkers seem to resolve duplicate shared object files differently when they appear in the traversal. Consider the following example:

              |            |
              | Executable |
              |            |
      |                         |
      |                         |
+-----v-----+            +------v----+
|           |            |           |
| |            | |
|           |            |           |
+-----+-----+            +-----------+
      |               /some-fixed-path/
|            |
|  |
|            |

In glibc the cache is keyed by the soname value on the shared object. That allows the first found at /some-fixed-path/ to be used for the one which depends on.

Unfortunately, musl does not support this functionality and ongoing discussions of inclusing it can be followed on the mailing list.


You must have Nix installed for development.

This package uses poetry2nix to easily setup a development environment.

> nix develop

A helping Makefile is provided to run all the linters and formatters.

> make lint

Note: I publish artifacts to cachix that you can use to develop faster.

> cachix use fzakaria


Included in the flake are different experiments for evaluating Shrinkwrap. In most cases they provide a Docker image (tar.gz) which can be loaded.


Creates a stamped version of the popular emacs editor similarly to the Guix experiment outlined in the blog post.

You can build the Docker image and inside will be emacs-wrapped as well as emacs and strace to recreate the experiment.

> nix build .#experiments.emacs
> docker load < result
643ace721190: Loading layer [==================================================>]  786.9MB/786.9MB
Loaded image: shrinkwrap-emacs-experiment:7jjlknqq660x1crrw7gm4m2qzalp71qj
> docker run -it emacs-experiment:7jjlknqq660x1crrw7gm4m2qzalp71qj /bin/bash
> patchelf --print-needed /bin/emacs-stamped

If you'd like you can pull the image directly from DockerHub via fmzakari/shrinkwrap-emacs-experiment:7jjlknqq660x1crrw7gm4m2qzalp71qj.

> docker pull fmzakari/shrinkwrap-emacs-experiment:7jjlknqq660x1crrw7gm4m2qzalp71qj
> docker run -it fmzakari/shrinkwrap-emacs-experiment:7jjlknqq660x1crrw7gm4m2qzalp71qj /bin/bash
> patchelf --print-needed /bin/emacs-stamped


Thanks to @trws for the inspiration and original version of this Python script.