devenv.yaml Reference: Inputs, Imports, and Project Settings

The devenv.yaml file sits alongside devenv.nix in your project root. It controls project-level concerns that live outside the Nix module system: which Nix inputs (dependencies) to pin, which remote or local environments to import, how nixpkgs is configured, and global devenv behaviors like shell auto-reload, profile selection, and secretspec integration.

This file is managed by the devenv inputs add command and updated by devenv update. You can also edit it directly.

A minimal devenv.yaml looks like this:

inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling

`inputs`

A map of Nix flake inputs. Each key is the input name used in your Nix expressions; the value is a configuration object describing where to fetch it. The default entry points to devenv’s curated nixpkgs rolling channel.

Field	Value
Type	`attribute set of input`
Default	`inputs.nixpkgs.url: github:cachix/devenv-nixpkgs/rolling`

`inputs.<name>.url`

The URI that identifies the flake or non-flake source. Supports all Nix flake URI formats.

inputs.<name>.url

string

required

URI specification of the input.

Common URI formats:

Format	Example
GitHub	`github:NixOS/nixpkgs/nixos-unstable`
GitHub (tagged)	`github:cachix/devenv/v1.4`
GitHub (dir)	`github:myorg/configs?dir=devenv`
GitLab	`gitlab:user/repo`
Sourcehut	`sourcehut:~user/repo`
Tarball	`https://example.com/pkg.tar.gz`
Local path	`path:/absolute/path` or `path:./relative`
Git	`git+https://github.com/org/repo`

`inputs.<name>.flake`

inputs.<name>.flake

boolean

default:"true"

Whether the input contains a flake.nix. Set to false for non-flake inputs such as plain tarballs or devenv.nix-only repositories.

`inputs.<name>.follows`

inputs.<name>.follows

string

Another input name to inherit from, ensuring version alignment. For example, setting follows: nixpkgs makes this input use the same nixpkgs revision as your top-level nixpkgs input, avoiding duplicate Nix store paths.

`inputs.<name>.inputs`

inputs.<name>.inputs

attribute set of input

Override nested inputs inside this dependency by name. Uses the same structure as the top-level inputs map.

`inputs.<name>.overlays`

inputs.<name>.overlays

list of string

default:"[]"

A list of overlay attribute paths to include from this input into nixpkgs. See the Overlays guide.

Example:

inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  nixpkgs-stable:
    url: github:NixOS/nixpkgs/nixos-24.11
  devenv:
    url: github:cachix/devenv
  my-configs:
    url: github:myorg/nix-configs
    flake: false
  fenix:
    url: github:nix-community/fenix
    inputs:
      nixpkgs:
        follows: nixpkgs

`imports`

A list of paths or input references that contribute additional devenv.nix and devenv.yaml configuration. Imported environments are deeply merged with the current environment, enabling reuse across projects.

imports

list of string

default:"[]"

Relative paths, absolute paths, or flake input references to import.

Import sources can be:

Type	Example
Relative path	`./shared`
Absolute path	`/home/user/devenv-base`
Input reference	`my-configs` (must be declared in `inputs`)

Example:

imports:
  - ./base          # local shared environment
  - my-configs      # from a flake input

When importing an input reference, devenv looks for devenv.nix and devenv.yaml in the root of that flake. Use the ?dir= query parameter in the input URL to point to a subdirectory.

`backend`

Select the Nix backend used to evaluate devenv.nix.

backend

nix

default:"nix"

The Nix evaluation backend. Currently only nix is supported.

`clean`

Options controlling environment variable cleaning when entering the shell.

clean.enabled

boolean

default:"false"

When true, strip all parent environment variables before entering the shell. Equivalent to the --clean CLI flag. New in devenv 1.0.

clean.keep

list of string

default:"[]"

A list of environment variable names to preserve even when clean.enabled is true. New in devenv 1.0.

clean:
  enabled: true
  keep:
    - HOME
    - USER
    - TERM

`impure`

impure

boolean

default:"false"

Relax the hermeticity of the environment, allowing access to the host system’s environment variables and file system. Equivalent to --impure. New in devenv 1.0.

`nixpkgs`

Fine-grained nixpkgs configuration controlling which packages are allowed and how the package set is built.

`nixpkgs.allow_unfree`

nixpkgs.allow_unfree

boolean

default:"false"

Allow packages with unfree licenses. New in devenv 1.7.

`nixpkgs.allow_broken`

nixpkgs.allow_broken

boolean

default:"false"

Allow packages marked as broken in nixpkgs. New in devenv 1.7.

`nixpkgs.allow_non_source`

nixpkgs.allow_non_source

boolean

default:"true"

Allow packages not built from source (nixpkgs default). New in devenv 1.7.

`nixpkgs.allow_unsupported_system`

nixpkgs.allow_unsupported_system

boolean

default:"false"

Allow packages that are not officially supported on the current system. New in devenv 2.0.5.

`nixpkgs.permitted_insecure_packages`

nixpkgs.permitted_insecure_packages

list of string

default:"[]"

A list of insecure package names to allow. New in devenv 1.7.

`nixpkgs.permitted_unfree_packages`

nixpkgs.permitted_unfree_packages

list of string

default:"[]"

A list of unfree package names to allow by name (more targeted than allow_unfree). New in devenv 1.9.

`nixpkgs.allowlisted_licenses`

nixpkgs.allowlisted_licenses

list of string

default:"[]"

A list of license attribute names to allow (e.g. gpl3Only, mit, asl20). See nixpkgs license list.

`nixpkgs.blocklisted_licenses`

nixpkgs.blocklisted_licenses

list of string

default:"[]"

A list of license attribute names to block (e.g. unfree, bsl11).

`nixpkgs.cuda_support`

nixpkgs.cuda_support

boolean

default:"false"

Enable CUDA support in nixpkgs. New in devenv 1.7.

`nixpkgs.cuda_capabilities`

nixpkgs.cuda_capabilities

list of string

default:"[]"

CUDA capabilities to select (e.g. ["8.0" "8.6"]). New in devenv 1.7.

`nixpkgs.rocm_support`

nixpkgs.rocm_support

boolean

default:"false"

Enable ROCm (AMD GPU compute) support in nixpkgs. New in devenv 2.0.7.

`nixpkgs.android_sdk.accept_license`

nixpkgs.android_sdk.accept_license

boolean

default:"false"

Accept the Android SDK license. Can also be set via NIXPKGS_ACCEPT_ANDROID_SDK_LICENSE=1.

`nixpkgs.per_platform`

nixpkgs.per_platform

attribute set of nixpkgs config

Per-platform nixpkgs configuration. The keys are system strings (e.g. x86_64-linux). Accepts all the same options as the top-level nixpkgs block. New in devenv 1.7.

nixpkgs:
  allow_unfree: true
  permitted_insecure_packages:
    - "openssl-1.1.1w"
  per_platform:
    x86_64-linux:
      cuda_support: true
      cuda_capabilities:
        - "8.0"
        - "8.6"

`profile`

profile

string

Default profile to activate on shell entry. Can be overridden by the --profile CLI flag. See Profiles. New in devenv 1.11.

`reload`

reload

boolean

default:"true"

Enable auto-reload of the shell when devenv.nix or devenv.yaml change. Can be overridden by --reload or --no-reload. New in devenv 2.0.

`require_version`

require_version

boolean | string

Version requirement for the devenv CLI. Set to true to require that the CLI version matches the modules version from the devenv input. Use a constraint string for more precise control: >=2.0, <3.0, =2.1.3, or a bare version string for an exact match. New in devenv 2.1.

require_version: ">=2.0"

`shell`

shell

string

default:"$SHELL or bash"

Default interactive shell to use when entering the devenv environment via devenv shell. Supported values: bash, zsh, fish, nu. Falls back to $SHELL then bash when unset. Can be overridden by the --shell CLI flag. New in devenv 2.1.

`strict_ports`

strict_ports

boolean

default:"false"

Error if a port is already in use instead of auto-allocating the next available port. Can be overridden by --strict-ports or --no-strict-ports. New in devenv 2.0.

`secretspec`

Integration with secretspec for declarative secrets management.

secretspec.enable

boolean

default:"false"

Enable secretspec integration. New in devenv 1.8.

secretspec.provider

string

Secretspec provider to use (e.g. keyring, 1password, dotenv). New in devenv 1.8.

secretspec.profile

string

Secretspec profile name to use. New in devenv 1.8.

secretspec.cachix_auth_token

string

default:"\"CACHIX_AUTH_TOKEN\""

Name of the secretspec secret to read the Cachix auth token from when CACHIX_AUTH_TOKEN is not set in the environment. This is the secret name in secretspec.toml, not the token value. New in devenv 2.1.3.

secretspec:
  enable: true
  provider: keyring
  profile: development

Complete example

inputs:
  nixpkgs:
    url: github:cachix/devenv-nixpkgs/rolling
  fenix:
    url: github:nix-community/fenix
    inputs:
      nixpkgs:
        follows: nixpkgs

imports:
  - ./shared-base

nixpkgs:
  allow_unfree: true
  permitted_insecure_packages:
    - "openssl-1.1.1w"

profile: backend

reload: true

require_version: ">=2.0"

secretspec:
  enable: true
  provider: keyring

Reference

Documentation Index

​inputs

​inputs.<name>.url

​inputs.<name>.flake

​inputs.<name>.follows

​inputs.<name>.inputs

​inputs.<name>.overlays

​imports

​backend

​clean

​impure

​nixpkgs

​nixpkgs.allow_unfree

​nixpkgs.allow_broken

​nixpkgs.allow_non_source

​nixpkgs.allow_unsupported_system

​nixpkgs.permitted_insecure_packages

​nixpkgs.permitted_unfree_packages

​nixpkgs.allowlisted_licenses

​nixpkgs.blocklisted_licenses

​nixpkgs.cuda_support

​nixpkgs.cuda_capabilities

​nixpkgs.rocm_support

​nixpkgs.android_sdk.accept_license

​nixpkgs.per_platform

​profile

​reload

​require_version

​shell

​strict_ports

​secretspec

​Complete example

Build docs developers (and LLMs) love

`inputs`

`inputs.<name>.url`

`inputs.<name>.flake`

`inputs.<name>.follows`

`inputs.<name>.inputs`

`inputs.<name>.overlays`

`imports`

`backend`

`clean`

`impure`

`nixpkgs`

`nixpkgs.allow_unfree`

`nixpkgs.allow_broken`

`nixpkgs.allow_non_source`

`nixpkgs.allow_unsupported_system`

`nixpkgs.permitted_insecure_packages`

`nixpkgs.permitted_unfree_packages`

`nixpkgs.allowlisted_licenses`

`nixpkgs.blocklisted_licenses`

`nixpkgs.cuda_support`

`nixpkgs.cuda_capabilities`

`nixpkgs.rocm_support`

`nixpkgs.android_sdk.accept_license`

`nixpkgs.per_platform`

`profile`

`reload`

`require_version`

`shell`

`strict_ports`

`secretspec`

Complete example