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: my-shell
#+begin_src nix
  { pkgs ? import <nixpkgs> {} }:
  pkgs.mkShell {
    buildInputs = [ pkgs.hello ];
  }
#+end_src

#+begin_src sh :nix-shell "my-shell"
  hello   # use 'hello' from 'my-shell'
#+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.

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

Melpa

(use-package org-nix-shell
  :hook (org-mode . org-nix-shell-mode))

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))

Customization

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