devenv

name	devenv
description	Use this when working in a project with devenv.nix, or when devenv.sh development environment setup, services, dependencies, or Nix packages are relevant.

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;
    };
    venv.enable = true;  # Activate the synced virtualenv in shell/direnv
    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 virtualenv is not activated

For Python projects using uv, set both languages.python.uv.sync.enable = true and languages.python.venv.enable = true. uv.sync installs dependencies; venv.enable activates the virtualenv so python and console scripts come from the project environment.

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
  ];
}