How To

Basics

Initialize a Project

When you want to create a new project, make a project directory (e.g. my-project) and cd into it. Run the following command.

nix flake init --template github:tweag/jupyenv

Your project directory will be populated with flake.nix and kernels.nix files.

Starting JupyterLab

Make sure you are in the top directory of your project (e.g. my-project), and run the following command.

nix run

The environment should start up with instructions on what to do next.

Kernels

After initializing your project with a flake template, it should have a kernels.nix file, with a minimally configured Python kernel.

Enable kernels

To enable any kernel, add a line like the following to the kernels.nix file.

kernel.<kernelType>.<kernelName>.enable = true;

<kernelType> is any of the kernels jupyenv supports (e.g. python, julia, ocaml, etc). <kernelName> can be virtually anything you want and is used so you can have multiple kernels of the same type with different configurations (e.g. example, scientific, testing, etc).

Conditions on <kernelName>

<kernelName> does have some limitations and must only contain ASCII letters, ASCII numbers, and the simple separators: - hyphen, . period, _ underscore. This limitation is because <kernelName> makes up part of the kernel specs name that Jupyter uses. See the relevant documentation if you are interested.

Additionally, because Nix uses period as separator for attribute sets, a <kernelName> with a period must be enclosed in double quotes (e.g. "my.example").

The following is an example kernels.nix file with multiple enabled kernels.

{...}: {
  kernel.python.scientific.enable = true;
  kernel.python.aiml.enable = true;
  kernel.julia.learning-math.enable = true;
  kernel.ocaml."functional.stuff".enable = true;
  kernel.bash.scripting_cli.enable = true;
}

Modifying kernel default options

To modify a kernel option, add a line like the following to the kernels.nix file. See the Options page for the available options for each kernel.

kernel.<kernelType>.<kernelName>.<option> = <value>;

The following is an example kernels.nix file with a Python kernel and different options being set.

{...}: {
  kernel.python.example.enable = true;
  kernel.python.example.displayName = "My Example Python Kernel";
  kernel.python.example.extraPackages = ps: [ps.numpy ps.scipy];
}

Conditions on the name option

Every kernel has a name option. Generally, you will not have to and should not change this value. If you do need to override the default, there are some limitations to be aware of.

The name option has the same character limitations as <kernelName> as described in the "Conditions on <kernelName>" admonition above.
name must only contain ASCII letters, ASCII numbers, and the simple separators: - hyphen, . period, _ underscore.
It is the exact value of the kernel spec name and must be unique. For example, the following configuration would cause unforeseen problems or might not build at all.
```
{...}: {
  ...
  kernel.python.example_1.name = "my-example-python";
  kernel.python.example_2.name = "my-example-python";
  ...
}
```

Julia kernel

The Julia kernel requires some stateful operations to work properly. If you have not initialized a project yet, see the Initialize a Project section.

Build the project with nix build .#.
Enter the Julia REPL with ./result/bin/julia.
Follow the commands from IJulia documentation to install IJulia.
```
julia
julia> using Pkg
julia> Pkg.add("IJulia")
```
After installing IJulia, make sure you exit the Julia REPL and are back at the top level of your project folder.
Start the JupyterLab environment with nix run.

Did something go wrong?

If a Julia kernel builds fine, but you get an error when trying to open a notebook, see if one of the error messages looks like the following.

ERROR: SystemError: opening file "/home/<USER>/.julia/packages/IJulia/<SLUG>/src/kernel.jl": No such file or directory

Here are some possible problems and how to fix them. It can be more than one.

The version of IJulia you have installed does not match what jupyenv expects. Check the version slug of IJulia with ls ~/.julia/packages/IJulia/. If this is different than the default value, you can override it by adding the following line to your kernel configuration.
```
  kernel.julia.<name>.ijuliaRev = <SLUG>;
```
Your depot path is not the default. If your Julia packages are not installed in "~/.julia", you can override it by adding the following line to your kernel configuration.
```
  kernel.julia.<name>.julia_depot_path = <PATH>;
```

Extensions

Extensions are currently being worked on to be reproducible.