Inputs

Inputs allow you to refer to Nix code outside of your project while preserving reproducibility.

Think of inputs as dependency management for your developer environment.

If you omit devenv.yaml, it defaults to:

devenv.yaml

inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  git-hooks:
    url: github:cachix/git-hooks.nix

The dependencies you mention as inputs are passed as an argument to the function.

For example, if you have a devenv.yaml file like:

devenv.yaml

inputs:
  nixpkgs-stable:
    url: github:NixOS/nixpkgs/nixos-23.11

You can access the stable packages via the inputs field:

devenv.nix

{ inputs, pkgs, ... }:

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

  enterShell = ''
    git --version
  ''
}

See basics for more about devenv.nix.

There are a few special inputs passed into devenv.nix:

devenv.nix

{ pkgs, lib, config, ... }:

{
  env.GREET = "hello";

  enterShell = ''
    echo ${config.env.GREET}
  '';
}

• pkgs is a nixpkgs input containing all of the available packages for your system.
• multiverse, when the nixpkgs-multiverse input is configured, provides packages indexed by version, such as multiverse.cmake."3.16.5". multiverse.pins resolves several versions at once through the fewest nixpkgs revisions and returns the packages. The original input is available as inputs."nixpkgs-multiverse".
• lib is a collection of functions for working with Nix data structures. You can use noogle to search for a function.
• config is the final resolved configuration for your developer environment, which you can use to reference any other options set in devenv.nix. Since Nix supports lazy evaluation, you can reference any option you define in the same file as long as it doesn’t reference itself!

Note

... is a catch-all pattern for any additional inputs, so you can safely omit the inputs you’re not using.

See devenv.yaml reference for all supported input options.

Supported URI formats

inputs.<name>.url is a URI format that allows importing external repositories, files, directories, and more as inputs to your development environment.

devenv supports the same URI specification for inputs as Nix Flakes.

For a more detailed description of the supported URI formats, see the Nix manual.

We’ll list the most common examples below.

GitHub

• github:NixOS/nixpkgs/master
• github:NixOS/nixpkgs/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://[email protected]/NixOS/nix?ref=v1.2.3
• git+https://git.somehost.tld/user/path?ref=branch&rev=fdc8ef970de2b4634e1b3dca296e1ed918459a9e
• git+file:///some/absolute/path/to/repo

Mercurial

• hg+https://...
• hg+ssh://...
• hg+file://...

Sourcehut

• sourcehut:~misterio/nix-colors/21c1a380a6915d890d408e9f22203436a35bb2de?host=hg.sr.ht

Tarballs

• tarball+https://example.com/foobar.tar.gz

Local files

Path inputs don’t respect .gitignore and will copy the entire directory to the Nix store. To avoid unnecessarily copying large development directories, consider using git+file instead.

• path:/path/to/repo
• file+https://
• file:///some/absolute/file.tar.gz

Following inputs

Inputs can also “follow” other inputs by name.

The two main use-cases for this are to:

• Inherit inputs from other devenv.yamls or external flake projects.
• Reduce the number of repeated inputs that need to be downloaded by overriding nested inputs.

follows are specified by name. Nested inputs can be referenced by name using / as a separator.

For example, to use a nixpkgs input from a shared base-project input:

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

Or to override the nixpkgs input of another input to reduce the number of times nixpkgs has to be downloaded:

inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  git-hooks:
    url: github:cachix/git-hooks.nix
    inputs:
      nixpkgs:
        follows: nixpkgs

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

Locking and updating inputs

When you run any of the commands, devenv resolves inputs like github:NixOS/nixpkgs/nixpkgs-unstable into a commit revision and writes them to devenv.lock. This ensures that your environment is reproducible.

To update an input to a newer commit, run devenv update or read the devenv.yaml reference to learn how to pin down the revision/branch at the input level.