devenv.sh Development Environments

Create fast, declarative, reproducible development environments using devenv.sh powered by Nix. Official docs: https://devenv.sh

For setting up specific programming languages, services, package managers, see:

• python-uv.md - Detailed Python/uv configuration
• services.md - Complete services configuration guide
• django.md - Django project setup and patterns

Initialize a New Environment

devenv init

This creates:

• devenv.yaml - Input configuration
• devenv.nix - Environment definition (where you configure everything)
• .envrc - direnv integration
• .gitignore - Ignores devenv artifacts

Remove comments from .gitignore after init.

The generated .envrc from devenv init works as-is now; you no longer need the old task-running workaround.

Edit devenv.yaml and replace the inputs section:

inputs:
  nixpkgs:
    url: github:NixOS/nixpkgs/nixpkgs-unstable

This gives access to the latest packages from nixpkgs.

Adding Nix Packages

Add system packages to your environment:

{ pkgs, ... }: {
  packages = with pkgs; [
    just        # always add this
    postgresql  # For psql CLI
    redis       # For redis-cli
  ];
}

Search for packages:

devenv search <package-name>

Only works after devenv init

Update Lock File

After changing inputs:

devenv update

This updates devenv.lock with pinned versions.

IMPORTANT: ALWAYS run devenv build after editing devenv.nix to make sure the configuration is working. Fix any problems that occurs during build.

Environment Variables

{
  env = {
    MY_VAR = "value";
    PYTHONUNBUFFERED = "1";
  };
}

Common Commands

• devenv init - Initialize new environment
• devenv shell - Enter development shell
• devenv up - Start services and processes (foreground)
• devenv up -d - Start services in background
• devenv processes stop - Stop all processes
• devenv test - Run tests
• devenv update - Update dependencies from devenv.yaml
• devenv search <pkg> - Search for packages
• devenv info - Show environment info

File Structure

Key files devenv manages:

• devenv.nix - Your environment configuration (commit this)
• devenv.yaml - Input sources (commit this)
• devenv.lock - Pinned versions (commit this)
• .envrc - direnv integration (commit this)
• .devenv/ - Build artifacts (don't commit)

Complete Example

{ pkgs, config, ... }: {
  # Python with uv
  languages.python = {
    enable = true;
    version = "3.12";
    uv = {
      enable = true;
      sync.enable = true;
    };
    libraries = with pkgs; [ postgresql stdenv.cc.cc.lib ];
  };

  # Services
  services = {
    postgres = {
      enable = true;
      package = pkgs.postgresql_15;
      initialDatabases = [{ name = "app"; }];
    };
    redis.enable = true;
  };

  # Packages
  packages = with pkgs; [
    git
    postgresql
    redis
  ];

  # Environment
  env = {
    DATABASE_URL = "postgresql://localhost/app";
    REDIS_URL = "redis://localhost:6379";
  };

  # Processes (devenv 2.0 native process manager with dependency support)
  processes = {
    web = {
      exec = "python manage.py runserver 0.0.0.0:8000";
      after = [ "devenv:processes:postgres" "devenv:processes:redis" ];
    };
    worker = {
      exec = "celery -A myapp worker";
      after = [ "devenv:processes:redis" ];
    };
  };

  # Scripts
  scripts = {
    migrate = {
      exec = "python manage.py migrate";
      description = "Run migrations";
    };
    test = {
      exec = "pytest";
      description = "Run tests";
    };
  };

  # Enable dotenv
  dotenv.enable = true;
}

Troubleshooting

Issue: Package not found

Search for it:

devenv search <package>

Ensure using nixpkgs-unstable in devenv.yaml.

Issue: Python package won't install

Add native dependencies to languages.python.libraries:

{
  languages.python.libraries = with pkgs; [
    postgresql  # For psycopg2
    stdenv.cc.cc.lib
  ];
}