Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cachix/devenv/llms.txt

Use this file to discover all available pages before exploring further.

Every devenv project is configured through a devenv.nix file. This file is written in the Nix expression language and describes your complete developer environment — packages, environment variables, shell hooks, and more — in a single declarative source of truth that works identically on every machine.

​
The devenv.nix File Structure

devenv.nix is a Nix function that accepts inputs and returns an attribute set (think of it as a typed key-value object, similar to a JSON object). Here is a minimal annotated example: 
{ pkgs, ... }: # (1)

{ # (2)
  env.GREET = "hello"; # (3)

  packages = [ pkgs.jq ];

  enterShell = ''
    echo $GREET
    jq --version
  ''; # (4)
}
Breaking down each part:
  1. { pkgs, ... }: — The file is a function. pkgs is a special input that gives you access to the entire Nixpkgs package collection. The ... catch-all means you don’t have to enumerate every possible input.
  2. { ... } — The function returns an attribute set. This is the environment definition.
  3. env.GREET = "hello"; — Attributes can be nested. env.* keys become shell environment variables. Values can be strings, numbers, booleans, lists, or references to other inputs.
  4. enterShell = ''...'' — Values can reference inputs such as pkgs. See Inputs for how to define custom inputs.
New to Nix? The Nix language tutorial is a 1–2 hour deep dive that will allow you to read any Nix file confidently.

​
Entering the Shell

Run devenv shell to build and activate the environment defined in devenv.nix. The enterShell script runs automatically on activation: 
$ devenv shell
Building shell ...
Entering shell ...

hello
jq-1.6

(devenv) $ echo $GREET
hello
The (devenv) prefix in the prompt indicates you are inside the managed environment. Every package listed in packages is available on $PATH, and every env.* variable is exported.

​
Environment Variables

Declare environment variables under the env attribute. Any key you set here is exported into the shell and visible to all scripts, processes, and tools running inside the environment: 
{ pkgs, ... }:

{
  env.GREET = "hello";
  env.DATABASE_URL = "postgres://localhost/mydb";
}
Variables are available immediately when the shell activates and are also visible to enterShell, tasks, processes, and tests.

​
Adding Packages

Add packages from Nixpkgs via the packages list. Use pkgs.<name> to reference any of the 100,000+ packages available: 
{ pkgs, ... }:

{
  packages = [ pkgs.jq pkgs.git pkgs.curl ];
}
You can search for available packages with: 
devenv search <NAME>

​
The enterShell Hook

enterShell runs a bash script every time you enter the environment with devenv shell. It is the right place for lightweight setup steps such as printing a welcome message or running a quick version check: 
{ pkgs, ... }:

{
  packages = [ pkgs.jq ];

  enterShell = ''
    echo "Welcome! Using jq $(jq --version)"
  '';
}
For more complex setup operations, consider using tasks instead of enterShell. Tasks provide better control over execution order, dependencies, and can run in parallel.

​
Viewing the Environment Summary

Run devenv info at any time to print a structured summary of the active environment — useful for verifying that variables, packages, and scripts are configured correctly: 
$ devenv info
...

# env
- DEVENV_DOTFILE: .../myproject/.devenv
- DEVENV_ROOT: .../myproject
- DEVENV_STATE: .../myproject/.devenv/state
- GREET: hello

# packages
- jq-1.6

# scripts

# processes
The output shows every environment variable (including devenv’s own built-in ones), every installed package, and any named scripts or processes you have declared.

​
Putting It All Together

Here is the full devenv.nix generated by devenv init, which demonstrates the most common configuration options side by side: 
{ pkgs, lib, config, inputs, ... }:

{
  # https://devenv.sh/basics/
  env.GREET = "devenv";

  # https://devenv.sh/packages/
  packages = [ pkgs.git ];

  # https://devenv.sh/languages/
  # languages.rust.enable = true;

  # https://devenv.sh/processes/
  # processes.dev.exec = "${lib.getExe pkgs.watchexec} -n -- ls -la";

  # https://devenv.sh/services/
  # services.postgres.enable = true;

  # https://devenv.sh/scripts/
  scripts.hello.exec = ''
    echo hello from $GREET
  '';

  # https://devenv.sh/basics/
  enterShell = ''
    hello         # Run scripts directly
    git --version # Use packages
  '';

  # https://devenv.sh/tasks/
  # tasks = {
  #   "myproj:setup".exec = "mytool build";
  #   "devenv:enterShell".after = [ "myproj:setup" ];
  # };

  # https://devenv.sh/tests/
  enterTest = ''
    echo "Running tests"
    git --version | grep --color=auto "${pkgs.git.version}"
  '';

  # https://devenv.sh/git-hooks/
  # git-hooks.hooks.shellcheck.enable = true;

  # See full reference at https://devenv.sh/reference/options/
}
Each commented-out section is a hint pointing to a different feature area. Uncomment and fill in what you need as your project grows.

Build docs developers (and LLMs) love

Get started for freeTalk to us