# How to Check the Status of Package Builds in twist.nix

> Learn to check package build status in twist.nix using depsCheck. Validate dependency constraints and get a JSON report for version mismatches. Ensure stable builds.

- Repository: [Emacs Twist/twist.nix](https://github.com/emacs-twist/twist.nix)
- Tags: how-to-guide
- Published: 2026-03-01

---

**Use the `depsCheck` attribute in `pkgs/emacs/default.nix` to validate dependency constraints, which returns a derivation that either succeeds silently or fails with a JSON report detailing version mismatches.**

The `twist.nix` repository provides a Nix-based Emacs Lisp package manager that enforces strict dependency versioning. When you declare packages in your configuration, the system must verify that all transitive dependencies satisfy version constraints before building. The build status check mechanism allows you to identify unsatisfied dependencies early in the evaluation process.

## Understanding the Build Status Check in twist.nix

The core validation logic resides in two key files. In `pkgs/emacs/default.nix`, the **`depsCheck`** attribute defines a derivation that invokes the validation tool. This tool is implemented in `pkgs/emacs/tools/check-versions.nix`, which computes the dependency graph and compares declared versions against available versions.

The check produces binary outcomes:

- **Success**: The derivation builds an empty file, indicating all packages have satisfying dependencies.
- **Failure**: The derivation fails with a non-zero exit code and exposes a detailed status report via the **`passthru`** attribute, containing specific version constraint violations.

## Checking Package Build Status Locally

### Quick Validation with nix build

Run the dependency check directly to see if your configuration is valid:

```bash
nix build .#depsCheck

```

If the command completes without error, all dependency constraints are satisfied. If it fails, you will see a warning message listing packages with insufficient dependencies, such as:

```

Warning: The following packages have insufficient dependencies:
  - magit: requires >= 2.90.0, found 2.89.0

```

### Detailed Inspection with nix eval

To programmatically inspect the status without triggering a build failure, evaluate the `passthru` attribute:

```bash
nix eval '(import ./test/twist.nix { pkgs = import <nixpkgs> {}; }).depsCheck.passthru' --json

```

This outputs a JSON object containing the full status report:

```json
{
  "status": {
    "errors": {
      "magit": {
        "required": "2.90.0",
        "current": "2.89.0",
        "satisfied": false
      }
    },
    "summary": {
      "magit": "magit"
    },
    "packages": {}
  }
}

```

The `status.errors` field maps package names to their version conflicts, while `status.summary` provides a concise list of affected packages.

## Automating Build Checks in CI

Integrate the dependency check into your continuous integration pipeline to catch version mismatches before deployment:

```nix
{ pkgs ? import <nixpkgs> {} }:

let
  cfg = import ./test/twist.nix { inherit pkgs; };
in
pkgs.runCommand "twist-deps-check" { } ''
  ${cfg.depsCheck} || {
    echo "Dependency check failed – see errors in passthru"
    exit 1
  }
  echo "All dependencies satisfied."
''

```

This derivation fails the CI job immediately when any package constraint is violated, printing the specific error details for debugging.

## Summary

- The **`depsCheck`** attribute in `pkgs/emacs/default.nix` validates all package dependencies in your twist.nix configuration.
- Run **`nix build .#depsCheck`** for a quick pass/fail validation of your package set.
- Inspect detailed failure reports via the **`passthru`** attribute, which exposes `status.errors` and `status.summary` as JSON.
- The validation logic is implemented in **`pkgs/emacs/tools/check-versions.nix`**, which computes dependency satisfaction across the graph.
- Integrate the check into CI pipelines using `nix eval` or `nix build` to prevent deployments with unsatisfied dependencies.

## Frequently Asked Questions

### What is the depsCheck attribute in twist.nix?

The `depsCheck` attribute is a derivation defined in `pkgs/emacs/default.nix` that performs a static analysis of your Emacs Lisp package dependencies. It invokes the version checking tool to ensure that every package in your configuration has dependencies that satisfy their declared version constraints, returning either an empty file on success or a failure with detailed error data.

### Where does twist.nix store the build status report?

The build status report is exposed through the derivation's **`passthru`** attribute, specifically under `passthru.status`. This JSON object contains three main fields: `errors` (detailed version mismatches), `summary` (a concise list of affected packages), and `packages` (full dependency graph information). You can access this data using `nix eval` without triggering a build failure.

### How do I fix unsatisfied dependency errors in twist.nix?

When `depsCheck` reports unsatisfied dependencies, examine the `status.errors` field to identify which packages require different versions. You have three resolution paths: upgrade the offending package to a compatible version in your lock file, override the dependency constraint if the version is functionally compatible, or remove the package if it cannot satisfy the dependency graph. After making changes, re-run `nix build .#depsCheck` to verify the fix.

### Can I check build status without building the packages?

Yes, the `depsCheck` validation is a **static analysis** that does not require building the actual Emacs Lisp packages. It only evaluates the dependency graph and version constraints defined in your Nix expressions. Use `nix eval` to inspect the `passthru` attribute or run `nix build .#depsCheck` to execute the check derivation, both of which operate purely at evaluation time without compiling package sources.