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.

Inputs are how devenv manages external Nix dependencies — think of them as dependency management for your developer environment. They let you refer to Nix code outside your project (packages, modules, flakes) while keeping your environment fully reproducible through a lock file.

​
Default inputs

If you omit devenv.yaml, devenv uses these defaults:
devenv.yaml
inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  git-hooks:
    url: github:cachix/git-hooks.nix
  • nixpkgs — the curated Nixpkgs snapshot that devenv modules are tested against.
  • git-hooks — the git-hooks.nix library used by devenv’s built-in hooks support.

​
Adding inputs

Declare inputs in devenv.yaml under the inputs key. Each input needs a url following the Nix Flakes URI format:
devenv.yaml
inputs:
  nixpkgs-stable:
    url: github:NixOS/nixpkgs/nixos-23.11

​
Adding inputs from the CLI

You can add an input to devenv.yaml without editing the file manually: 
$ devenv inputs add nixpkgs-stable github:NixOS/nixpkgs/nixos-23.11
To make the new input follow an existing input: 
$ devenv inputs add my-input github:org/repo --follows nixpkgs

​
Accessing inputs in devenv.nix

Inputs declared in devenv.yaml are passed as arguments to the function in devenv.nix. Use the inputs argument to access them:
devenv.nix
{ inputs, pkgs, ... }:

let
  pkgs-stable = import inputs.nixpkgs-stable { system = pkgs.stdenv.system; };
in {
  packages = [ pkgs-stable.git ];

  enterShell = ''
    git --version
  '';
}

​
Special built-in arguments

Beyond named inputs, devenv always passes these special arguments into devenv.nix:
devenv.nix
{ pkgs, lib, config, ... }:

{
  env.GREET = "hello";

  enterShell = ''
    echo ${config.env.GREET}
  '';
}
  • pkgs — the nixpkgs input pre-imported for your system, giving you access to all available packages.
  • lib — a collection of helper functions for working with Nix data structures. Search them at noogle.dev.
  • config — the fully resolved configuration for your developer environment. Because Nix uses lazy evaluation, you can reference any option you define in the same file as long as it doesn’t reference itself.
... is a catch-all pattern for any additional inputs, so you can safely omit inputs you’re not using.

​
Supported URI formats

inputs.<name>.url accepts the same URI formats as Nix Flakes. Below are the most common examples.

GitHub

github:NixOS/nixpkgs/master
github:NixOS/nixpkgs?rev=238b18d7b2c8239f676358634bfb32693d3706f3
github:org/repo?dir=subdir
github:org/repo?ref=v1.0.0

GitLab

gitlab:owner/repo/branch
gitlab:owner/repo/commit
gitlab:owner/repo?host=git.example.org

Git repositories

git+ssh://git@github.com/NixOS/nix?ref=v1.2.3
git+https://git.somehost.tld/user/path?ref=branch&rev=fdc8ef9
git+file:///some/absolute/path/to/repo

Tarballs & local files

tarball+https://example.com/foobar.tar.gz
path:/path/to/repo
file+https://
file:///some/absolute/file.tar.gz
Other supported schemes include hg+https://, hg+ssh://, and sourcehut:~user/repo. For the full URI specification, see the Nix manual.
Path inputs (path:/path/to/repo) don’t respect .gitignore and will copy the entire directory to the Nix store. To avoid copying large development directories unnecessarily, use git+file: instead.

​
Following inputs

Inputs can “follow” other inputs by name. This is useful for two scenarios:
  • Inheriting inputs from another devenv.yaml or external flake project.
  • Reducing duplication by sharing one nixpkgs instance across multiple inputs.
Nested inputs are referenced using / as a separator.

​
Inherit nixpkgs from another project

devenv.yaml
inputs:
  base-project:
    url: github:owner/repo
  nixpkgs:
    follows: base-project/nixpkgs

​
Reduce repeated downloads

Override a nested input so it reuses your top-level nixpkgs instead of fetching its own:
devenv.yaml
inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  git-hooks:
    url: github:cachix/git-hooks.nix
    inputs:
      nixpkgs:
        follows: nixpkgs

​
Locking and updating inputs

When you run any devenv command, inputs like github:NixOS/nixpkgs/nixpkgs-unstable are resolved to a specific commit revision and written to devenv.lock. This ensures every team member gets an identical environment. To update all inputs to their latest revisions: 
$ devenv update
To pin a specific revision or branch without running devenv update, set rev or ref directly in the url field — for example github:NixOS/nixpkgs?rev=238b18d7b2c8239f676358634bfb32693d3706f3. See the devenv.yaml reference for all supported input options.

Build docs developers (and LLMs) love

Get started for freeTalk to us