devshell

Simple per-project developer environments.

Example:

perSystem = { config, pkgs, ... }: {
  devshells.default = {
    env = [
      {
        name = "HTTP_PORT";
        value = 8080;
      }
    ];
    commands = [
      {
        help = "print hello";
        name = "hello";
        command = "echo hello";
      }
    ];
    packages = [
      pkgs.cowsay
    ];
  };
};

See also the devshell project page

Installation

To use these options, add to your flake inputs:

devshell.url = "github:numtide/devshell";

and inside the mkFlake:

imports = [
  inputs.devshell.flakeModule
];

Run nix flake lock and you're set.

Options

perSystem.devshells

perSystem.devshells.<name>.commands

perSystem.devshells.<name>.commands.*.package

perSystem.devshells.<name>.commands.*.category

perSystem.devshells.<name>.commands.*.command

perSystem.devshells.<name>.commands.*.help

perSystem.devshells.<name>.commands.*.name

perSystem.devshells.<name>.devshell.packages

perSystem.devshells.<name>.devshell.packagesFrom

perSystem.devshells.<name>.devshell.interactive.<name>.deps

perSystem.devshells.<name>.devshell.interactive.<name>.text

perSystem.devshells.<name>.devshell.load_profiles

perSystem.devshells.<name>.devshell.meta

perSystem.devshells.<name>.devshell.motd

perSystem.devshells.<name>.devshell.name

perSystem.devshells.<name>.devshell.prj_root_fallback

perSystem.devshells.<name>.devshell.prj_root_fallback.eval

perSystem.devshells.<name>.devshell.prj_root_fallback.name

perSystem.devshells.<name>.devshell.prj_root_fallback.prefix

perSystem.devshells.<name>.devshell.prj_root_fallback.unset

perSystem.devshells.<name>.devshell.prj_root_fallback.value

perSystem.devshells.<name>.devshell.startup.<name>.deps

perSystem.devshells.<name>.devshell.startup.<name>.text

perSystem.devshells.<name>.env

perSystem.devshells.<name>.env.*.eval

perSystem.devshells.<name>.env.*.name

perSystem.devshells.<name>.env.*.prefix

perSystem.devshells.<name>.env.*.unset

perSystem.devshells.<name>.env.*.value

perSystem.devshells.<name>.serviceGroups

perSystem.devshells.<name>.serviceGroups.<name>.description

perSystem.devshells.<name>.serviceGroups.<name>.name

perSystem.devshells.<name>.serviceGroups.<name>.services

perSystem.devshells.<name>.serviceGroups.<name>.services.<name>.command

perSystem.devshells.<name>.serviceGroups.<name>.services.<name>.name

perSystem.devshells

Configure devshells with flake-parts.

Not to be confused with devShells, with a capital S. Yes, this is unfortunate.

Each devshell will also configure an equivalent devShells.

Used to define devshells. not to be confused with devShells

Type: lazy attribute set of (submodule)

Default: { }

Declared by:

devshell/flake-module.nix

perSystem.devshells.<name>.commands

Add commands to the environment.

Type: list of (submodule)

Default: [ ]

Example:

[
  {
    help = "print hello";
    name = "hello";
    command = "echo hello";
  }

{ package = "nixpkgs-fmt"; category = "formatter"; } ]

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.commands.*.package

Used to bring in a specific package. This package will be added to the environment.

Type: null or (package or string convertible to it)

Default: null

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.commands.*.category

Set a free text category under which this command is grouped and shown in the help menu.

Type: string

Default: "[general commands]"

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.commands.*.command

If defined, it will add a script with the name of the command, and the content of this value.

By default it generates a bash script, unless a different shebang is provided.

Type: null or string

Default: null

Example:

''
  #!/usr/bin/env python
  print("Hello")
''

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.commands.*.help

Describes what the command does in one line of text.

Type: null or string

Default: null

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.commands.*.name

Name of this command. Defaults to attribute name in commands.

Type: null or string

Default: null

Declared by:

devshell/modules/commands.nix

perSystem.devshells.<name>.devshell.packages

The set of packages to appear in the project environment.

Those packages come from https://nixos.org/NixOS/nixpkgs and can be searched by going to https://search.nixos.org/packages

Type: list of (package or string convertible to it)

Default: [ ]

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.packagesFrom

Add all the build dependencies from the listed packages to the environment.

Type: list of (package or string convertible to it)

Default: [ ]

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.interactive.<name>.deps

A list of other steps that this one depends on.

Type: list of string

Default: [ ]

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.interactive.<name>.text

Script to run.

Type: string

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.load_profiles

Whether to enable load etc/profiles.d/*.sh in the shell.

Type: boolean

Default: false

Example: true

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.meta

Metadata, such as ‘meta.description’. Can be useful as metadata for downstream tooling.

Type: attribute set of anything

Default: { }

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.motd

Message Of The Day.

This is the welcome message that is being printed when the user opens the shell.

You may use any valid ansi color from the 8-bit ansi color table. For example, to use a green color you would use something like {106}. You may also use {bold}, {italic}, {underline}. Use {reset} to turn off all attributes.

Type: string

Default:

''
  {202}🔨 Welcome to devshell{reset}
  $(type -p menu &>/dev/null && menu)
''

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.name

Name of the shell environment. It usually maps to the project name.

Type: string

Default: "devshell"

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.prj_root_fallback

If IN_NIX_SHELL is nonempty, or DIRENV_IN_ENVRC is set to ‘1’, then PRJ_ROOT is set to the value of PWD.

This option specifies the path to use as the value of PRJ_ROOT in case IN_NIX_SHELL is empty or unset and DIRENV_IN_ENVRC is any value other than ‘1’.

Set this to null to force PRJ_ROOT to be defined at runtime (except if IN_NIX_SHELL or DIRENV_IN_ENVRC are defined as described above).

Otherwise, you can set this to a string representing the desired default path, or to a submodule of the same type valid in the ‘env’ options list (except that the ‘name’ field is ignored).

Type: null or ((submodule) or non-empty string convertible to it)

Default:

{
  eval = "$PWD";
}

Example:

{
  # Use the top-level directory of the working tree
  eval = "$(git rev-parse --show-toplevel)";
};

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.prj_root_fallback.eval

Like value but not evaluated by Bash. This allows to inject other variable names or even commands using the $() notation.

Type: null or string

Default: null

Example: "$OTHER_VAR"

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.devshell.prj_root_fallback.name

Name of the environment variable

Type: string

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.devshell.prj_root_fallback.prefix

Prepend to PATH-like environment variables.

For example name = “PATH”; prefix = “bin”; will expand the path of ./bin and prepend it to the PATH, separated by ‘:’.

Type: null or string

Default: null

Example: "bin"

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.devshell.prj_root_fallback.unset

Whether to enable unsets the variable.

Type: boolean

Default: false

Example: true

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.devshell.prj_root_fallback.value

Shell-escaped value to set

Type: null or string or signed integer or boolean or package

Default: null

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.devshell.startup.<name>.deps

A list of other steps that this one depends on.

Type: list of string

Default: [ ]

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.devshell.startup.<name>.text

Script to run.

Type: string

Declared by:

devshell/modules/devshell.nix

perSystem.devshells.<name>.env

Add environment variables to the shell.

Type: list of (submodule)

Default: [ ]

Example:

[
  {
    name = "HTTP_PORT";
    value = 8080;
  }
  {
    name = "PATH";
    prefix = "bin";
  }
  {
    name = "XDG_CACHE_DIR";
    eval = "$PRJ_ROOT/.cache";
  }
  {
    name = "CARGO_HOME";
    unset = true;
  }
]

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.env.*.eval

Like value but not evaluated by Bash. This allows to inject other variable names or even commands using the $() notation.

Type: null or string

Default: null

Example: "$OTHER_VAR"

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.env.*.name

Name of the environment variable

Type: string

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.env.*.prefix

Prepend to PATH-like environment variables.

For example name = “PATH”; prefix = “bin”; will expand the path of ./bin and prepend it to the PATH, separated by ‘:’.

Type: null or string

Default: null

Example: "bin"

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.env.*.unset

Whether to enable unsets the variable.

Type: boolean

Default: false

Example: true

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.env.*.value

Shell-escaped value to set

Type: null or string or signed integer or boolean or package

Default: null

Declared by:

devshell/modules/env.nix

perSystem.devshells.<name>.serviceGroups

Add services to the environment. Services can be used to group long-running processes.

Type: attribute set of (submodule)

Default: { }

Declared by:

devshell/modules/services.nix

perSystem.devshells.<name>.serviceGroups.<name>.description

Short description of the service group, shown in generated commands

Type: null or string

Default: null

Declared by:

devshell/modules/services.nix

perSystem.devshells.<name>.serviceGroups.<name>.name

Name of the service group. Defaults to attribute name in groups.

Type: null or string

Default: null

Declared by:

devshell/modules/services.nix

perSystem.devshells.<name>.serviceGroups.<name>.services

Attrset of services that should be run in this group.

Type: attribute set of (submodule)

Default: { }

Declared by:

devshell/modules/services.nix

perSystem.devshells.<name>.serviceGroups.<name>.services.<name>.command

Command to execute.

Type: string

Declared by:

devshell/modules/services.nix

perSystem.devshells.<name>.serviceGroups.<name>.services.<name>.name

Name of this service. Defaults to attribute name in group services.

Type: null or string

Default: null

Declared by:

devshell/modules/services.nix