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.

devenv is a fast, declarative, and reproducible developer environment tool built on top of Nix. It lets you define your entire development setup — packages, environment variables, services, scripts, and more — in a single devenv.nix file that works identically across Linux, macOS, and Windows (via WSL2).
1
Install Nix
2
Nix is the package manager that powers devenv. Choose your platform to get the right install command:
3
Linux
sh <(curl -L https://nixos.org/nix/install) --daemon
macOS
curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install
The installer above is the recommended option for macOS. It handles OS upgrades and has better support for Apple silicon. If you prefer the classic installer, use:
sh <(curl -L https://nixos.org/nix/install)
Upgrade BashmacOS ships with an ancient version of Bash due to licensing reasons. Install a newer version from Nixpkgs to avoid evaluation errors:
nix-env --install --attr bashInteractive -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable
Windows (WSL2)
sh <(curl -L https://nixos.org/nix/install) --no-daemon
Docker
docker run -it nixos/nix
4
Install devenv
5
With Nix available, install the devenv CLI using whichever method matches your setup:
6
Nix env (newcomers)
nix-env --install --attr devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable
Nix profiles (requires experimental flags)
nix profile install nixpkgs#devenv
NixOS / nix-darwin
Add devenv to your system packages in configuration.nix:
environment.systemPackages = [
  pkgs.devenv
];
home-manager
Add devenv to your user packages in home.nix:
home.packages = [
  pkgs.devenv
];
7
Configure a GitHub access token (optional)
8
The Nix ecosystem relies heavily on GitHub for hosting and distributing source code, including Nixpkgs itself. Without authentication, Nix makes many unauthenticated requests to the GitHub API, which can trigger rate limiting — especially on fresh installs or CI machines.
9
Create a token with no extra permissions at https://github.com/settings/personal-access-tokens/new, then add it to ~/.config/nix/nix.conf:
10
access-tokens = github.com=<GITHUB_TOKEN>
11
Initialize your project
12
Inside your project directory, run devenv init to scaffold the necessary files:
13
$ devenv init
• Creating devenv.nix
• Creating devenv.yaml
• Creating .gitignore
14
Three files are created:
15
  • devenv.nix — the main environment definition: packages, services, scripts, environment variables, and more.
  • devenv.yaml — declares inputs (e.g., Nixpkgs version) and imports.
  • .gitignore — pre-populated with entries for devenv’s generated state directories.
    • 16
    Enter the environment
    17
    Activate your developer environment with:
    18
    devenv shell
    19
    devenv builds the environment described in devenv.nix and drops you into a shell that has every declared package and variable available.

    ​
    Key Commands

    Once your environment is initialized, devenv provides a rich set of commands for day-to-day development:
    CommandDescription
    devenv initScaffold devenv.yaml, devenv.nix, and .gitignore
    devenv generateGenerate devenv.yaml and devenv.nix using AI
    devenv shellActivate the developer environment
    devenv testBuild the environment and run all checks (useful in CI)
    devenv search <NAME>Search packages matching NAME in the Nixpkgs input
    devenv updateUpdate and pin inputs from devenv.yaml into devenv.lock
    devenv gcDelete unused environments to free disk space
    devenv upStart processes in the foreground
    devenv processes downStop background processes
    devenv infoPrint a summary of the current environment
    devenv build <attr>Build an attribute from devenv.nix
    devenv eval <attr>Evaluate an attribute and return JSON
    devenv replLaunch an interactive Nix REPL for inspecting the environment
    devenv tasks run <task>Run tasks
    devenv container build|copy|runManage containers
    devenv inputs add <name> <url>Add an input to devenv.yaml
    devenv lspStart the nixd language server for devenv.nix
    devenv mcpLaunch the MCP server for AI assistant integration

    ​
    Updating

    ​
    Update the devenv CLI

    nix-env --upgrade --attr devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

    ​
    Update project inputs

    Inputs such as Nixpkgs and devenv modules are downloaded and pinned in a devenv.lock lockfile. Periodically refresh them with: 
    devenv update
    Learn more about managing inputs in the Inputs guide.

    ​
    Show Your Support

    Add a badge to your project’s README to let others know it’s built with devenv: 
    [![Built with devenv](https://devenv.sh/assets/devenv-badge.svg)](https://devenv.sh)
    Built with devenv

    Build docs developers (and LLMs) love

    Get started for freeTalk to us