nix-thunk: Lightweight dependency management with Nix

[ bsd3, git, library, nix, program ] [ Propose Tags ]

nix-thunk lets you manage source code dependencies in a lightweight and reproducible way, using Nix. Each source repository is represented by a stub directory, which refers to the original Git repository. nix-thunk can easily update these dependencies.

If you need to make improvements to the original repositories, nix-thunk can unpack them in-place, so that changes can be tested right away, and then pack them back up when you're done. This makes it easy to send a pull request to the upstream repo while your project continues on a fork, then switch back to upstream once your pull request has been merged.

[Skip to Readme]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS],,,,,,,, (info)
Change log
Dependencies aeson (>= && <2.3), aeson-pretty (>=0.8.7 && <0.9), base (>= && <4.19), bytestring (>= && <0.12), cli-extras (>= && <0.3), cli-git (>= && <0.3), cli-nix (>= && <0.3), containers (>= && <0.7), cryptonite (>=0.25 && <0.31), data-default (>= && <0.8), directory (>= && <1.4), either (>= && <5.1), exceptions (>=0.10.3 && <0.11), extra (>=1.6.18 && <1.8), filepath (>= && <1.5), github (>=0.25 && <0.30), here (>=1.2.13 && <1.3), lens (>=4.17.1 && <5.4), logging-effect (>=1.3.4 && <1.5), megaparsec (>=7.0.5 && <9.7), memory (>=0.14 && <0.19), modern-uri (>= && <0.4), monad-logger (>=0.3.30 && <0.4), mtl (>=2.2.2 && <2.4), nix-thunk, optparse-applicative (>= && <0.17), temporary (>=1.3 && <1.4), text (>= && <1.3), time (>= && <1.12), unix (>= && <2.8), which (>=0.2 && <0.3), yaml (>= && <0.12) [details]
License BSD-3-Clause
Copyright Obsidian Systems LLC 2020-2022
Author Obsidian Systems LLC
Category Nix, Git
Bug tracker
Source repo head: git clone git://
Uploaded by abrar at 2024-05-27T23:53:40Z
Distributions NixOS:
Executables nix-thunk
Downloads 823 total (29 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user [build log]
All reported builds failed as of 2024-05-28 [all 2 reports]

Readme for nix-thunk-

[back to package description]


Haskell Hackage Github CI BSD3 License

nix-thunk is a lightweight Nix dependency manager, focused on making it easy to contribute improvements back to libraries you depend on.

nix-thunk does this by creating and managing "thunks" - directories that stand in for full git repositories. Like git submodules, they pin a specific commit of the target repository, but unlike git submodules, you don't have to clone them to use them. nix-thunk makes them "transparent" to Nix scripts, so any script that calls import path/to/some/thunk will work the same on the thunk as it does on the original repository.


nix-env -f -iA command

WARNING: It is not possible to compile nix-thunk without Nix. To ensure that packed thunks are buildable even in environments where diamond paths are unavailable (specifically <nixpkgs>), nix-thunk must be built with knowledge of a known-good nixpkgs, and for nix-thunk to be able to manipulate these thunks, it must always be the same version of nixpkgs.

Command Usage

Create a dependency

nix-thunk create

If you have already cloned the dependency as a git repository, you can just pack it instead:

nix-thunk pack some-dep

Work on a dependency

If you discover a bug fix or improvement that your dependency needs, you can use nix-thunk unpack path/to/your/dependency to turn the thunk back into a full checkout of the repository. Your Nix scripts should continue working, and you can modify the dependency's source code, push it to a branch or a fork, send a pull request, and then use nix-thunk pack path/to/your/dependency to pack it back up into a thunk. When the dependency accepts your pull request, you can easily update the thunk.

nix-thunk unpack some-dep
# Improve some-dep and push your work to a branch
nix-thunk pack some-dep

Update a dependency

For routine updates, you can run nix-thunk update path/to/your/dependency to point the thunk at the latest version of the dependency without needing to do a nix-thunk unpack or a git clone.

nix-thunk update some-dep

Nix Usage

The default.nix file in this repository also defines the nix function, thunkSource. This can be used in your nix files to access the contents of thunks. In the following example, a thunk is used in place of the source location argument to callCabal2nix. thunkSource works whether the thunk is packed or unpacked, making it convenient to run nix commands with modified thunks.

  haskellPackages = pkgs.haskell.packages.ghc865.override {
    overrides = self: super: {
      which = self.callCabal2nix "which" (thunkSource ./dep/which) {};

You can also represent in nix all the thunks of a given directory

let sources = nix-thunk.mapSubdirectories nix-thunk.thunkSource ./dep;
{ which = self.callCabal2nix "which" sources.which {}; }

You can also access subfolders of a thunk. For example:

  imports = [ "${builtins.fetchTarball <some-tar-url>}/path/to/subfolder" ];


  imports = [ "${nix-thunk.thunkSource <thunk-location>}/path/to/subfolder>" ];


Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. See the contribution guide for more details.



Obsidian Systems