org-nix-shell

Buffer-local nix-shell environments in org-mode.

Use nix shells directly in org-mode source blocks. org-nix-shell works by seamlessly inheriting a nix shell environment using direnv before executing org-babel source blocks.

Quickstart

#+name: nix-shell
#+begin_src nix
  { pkgs ? import <nixpkgs> {} }:
  pkgs.mkShell {
    buildInputs = [ pkgs.hello ];
  }
#+end_src

#+begin_src sh :nix-shell "nix-shell"  # load named nix-shell src block
  hello   # use 'hello' dependency
#+end_src

Enable org-nix-shell-mode and evaluate or export the buffer. See demo.org with examples for Python and C.

Usage

First create a nix shell in a named source block.

#+name: <name>
#+begin_src nix
  { pkgs ? import <nixpkgs> {} }:
  pkgs.mkShell {
    buildInputs = with pkgs; [ python3 ];
  }
#+end_src

Source blocks with a :nix-shell <name> header argument will use the nix shell environment specified by <name>; where <name> is the corresponding named source block in the same buffer. Other source blocks should be unaffected and you can explicitly set :nix-shell 'nil to not depend on any nix shell.

To use the nix shell above we can do:

#+begin_src python :nix-shell <name>
  print("hello from python")
#+end_src

There are three ways to configure the :nix-shell header property; also see Using Header Arguments (The Org Manual). In increasing order of priority they are:

Buffer Scope

#+property: header-args: :nix-shell <name>

Subtree Scope

* sample header
  :PROPERTIES:
  :header-args:    :nix-shell <name>
  :END:

Source Block Scope

#+begin_src python :nix-shell <name>
  print("hello from python")
#+end_src

Installation

Make sure nix-shell and direnv is installed on your system (nix-community/nix-direnv#Installation).

Manual

First, put org-nix-shell.el in your load path. Then evaluate:

(require 'org-nix-shell)
(add-hook 'org-mode-hook 'org-nix-shell-mode)

Melpa

See Pull Request #8903.

Straight

(use-package org-nix-shell
  :straight '(org-nix-shell
              :type git
              :host github
              :repo "AntonHakansson/org-nix-shell")
  :hook (org-mode . org-nix-shell-mode))

Nix

With emacsWithPackagesFromUsePackage you can do:

pkgs.emacsWithPackagesFromUsePackage {
  config = ./init.el;
  extraEmacsPackages = epkgs:
    [(epkgs.trivialBuild rec {
      pname = "org-nix-shell";
      version = "v0.3.2";
      packageRequires = [ epkgs.envrc ];
      src = pkgs.fetchFromGitHub {
        owner = "AntonHakansson";
        repo = pname;
        rev = version;
        sha256 = lib.fakeHash;
      };
    })];
};

Customization

M-x customize-group org-nix-shell to see available customizable variables.