devenv

To ensure developer environments are reproducible, devenv uses a lockfile called devenv.lock. Each input declared in devenv.yaml is resolved to an exact revision and stored in this lockfile. This prevents different machines from resolving floating branches or tags to different commits.

There is no separate "create lock" step; devenv.lock is automatically created or updated whenever you run devenv commands on the project.

How it works

The hook monitors directory changes and performs the following:

1. Searches upwards from the current directory for a devenv.yaml or devenv.nix file.
2. Verifies the project against the trust database.
3. If trusted, it executes devenv shell in a subshell.

Automatic deactivation

When you cd out of the project directory or any of its subdirectories, the devenv subshell exits automatically, returning you to your normal shell.

Re-entry protection

To prevent nesting, the hook will not spawn a new environment if you are already inside a devenv shell for that same project. Navigating into subdirectories of the current project keeps the current shell active; only navigating outside the project triggers deactivation.

In Nix-based environments, starting programs can be slow due to a 'stat storm'. Because Nix stores packages in unique /nix/store/<hash>-<name>/lib directories rather than global paths like /usr/lib, the dynamic loader must search through many DT_RUNPATH entries to find shared libraries.

For every directory in the DT_RUNPATH, the loader also probes glibc-hwcaps subdirectories (e.g., x86-64-v3), multiplying the number of failing openat() calls. This overhead is particularly noticeable on slow disks, network filesystems (NFS), or cold caches.

Example of overhead:

• devenv version (83 libraries, 12 DT_RUNPATH dirs) results in ~486 failing opens.
• imagemagick (91 libraries, 35 DT_RUNPATH dirs) results in ~1225 failing opens.

To prevent Nix from deleting active developer environments from the store, devenv maintains garbage collection (GC) roots.

Each time you activate a shell or run a devenv command that evaluates your environment, a timestamped symlink is created inside $DEVENV_HOME/gc/ (which defaults to ~/.local/share/devenv/gc/). This symlink points to the Nix store path backing your environment. Only the latest successful invocation per project folder is kept; older generations are cleaned up automatically.

In devenv, all processes are exposed as tasks with the naming convention devenv:processes:<name>. You can use this to orchestrate startup and shutdown sequences by defining tasks that run before or after a specific process.

Execute setup tasks before a process

Use the before attribute in a task to ensure a command (like database migrations) runs before the target process starts.

Run cleanup tasks after a process

Use the after attribute in a task to ensure cleanup commands (like removing PID files or temporary directories) run after the target process stops.

# Example: Running migrations before a backend process
{
  processes.backend = {
    exec = "cargo run --release";
  };

  tasks."db:migrate" = {
    exec = "diesel migration run";
    before = [ "devenv:processes:backend" ];
  };
}

If Python packages (like Pillow or grpcio) fail to find native libraries, add those libraries to the global packages list. devenv will automatically add them to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS).

For more granular control, use the libraries option.

{ packages = [ pkgs.cairo pkgs.zlib ];

  languages.python = {
    enable = true;
    venv.enable = true;
    venv.requirements = ''
      pillow
      grpcio-tools
    '';
  };
}

devenv 2.0 uses SecretSpec for declarative, provider-agnostic secrets management. You declare required and optional secrets in a secretspec.toml file. Developers can then provide these secrets via backends like keyring, dotenv, 1Password, or environment variables. This prevents secrets from being silently leaked to background processes or coding agents.

# secretspec.toml
[project]
name = "myapp"
revision = "1.0"

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
STRIPE_KEY = { description = "Stripe API secret key", required = true }
SENTRY_DSN = { description = "Sentry error tracking DSN", required = false }

You can set up SecretSpec by initializing a configuration or migrating an existing .env file.

Initialize configuration

Run the following command to select your preferred provider backend (e.g., keyring, onepassword, dotenv, env, lastpass) and your default profile:

$ secretspec config init

Migrate from .env

To create a secretspec.toml file based on your existing .env file, use:

$ secretspec init --from dotenv

For greater flexibility, you can define outputs using the module system's options block. This allows you to integrate outputs into your configuration as typed options.

When defining an option that represents an output, use config.lib.types.outputOf lib.types.package (or config.lib.types.output if you do not want to specify the output option type). devenv will automatically include these in the build process.

{ pkgs, lib, config, ... }: {
  options = {
    myapp.package = pkgs.lib.mkOption {
      type = config.lib.types.outputOf lib.types.package;
      description = "The package for myapp";
      default = import ./myapp { inherit pkgs; };
      defaultText = "myapp";
    };
  };

  config = {
    outputs.git = pkgs.git;
  };
}