- an executable file, either on the file system:

  ```nix
  { stdenv }:
  stdenv.mkDerivation {
    # ...
    passthru.updateScript = ./update.sh;
  }
  ```

  or inside the expression itself:

  ```nix
  { stdenv, writeScript }:
  stdenv.mkDerivation {
    # ...
    passthru.updateScript = writeScript "update-zoom-us" ''
      #!/usr/bin/env nix-shell
      #!nix-shell -i bash -p curl pcre2 common-updater-scripts

      set -eu -o pipefail

      version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcre2grep -o1 '/(([0-9]\.?)+)/')"
      update-source-version zoom-us "$version"
    '';
  }
  ```

- a list, a script file followed by arguments to be passed to it:

  ```nix
  { stdenv }:
  stdenv.mkDerivation {
    # ...
    passthru.updateScript = [
      ../../update.sh
      pname
      "--requested-release=unstable"
    ];
  }
  ```

- an attribute set containing:
  - `command`

    A string or list in the [format expected by `passthru.updateScript`][automatic-package-updates]

  - `attrPath` (optional)

    A string containing the canonical attribute path for the package.

    If present, it will be passed to the update script instead of the attribute path on which the package was discovered during Nixpkgs traversal.

  - `supportedFeatures` (optional)

    A list of the [extra features the script supports][supported-features].

    ```nix
    { stdenv }:
    stdenv.mkDerivation rec {
      pname = "my-package";
      # ...
      passthru.updateScript = {
        command = [
          ../../update.sh
          pname
        ];
        attrPath = pname;
        supportedFeatures = [
          # ...
        ];
      };
    }
    ```

### How are update scripts executed?

Update scripts are to be invoked by the [automatic package update script](../maintainers/scripts/update.nix).
You can run `nix-shell maintainers/scripts/update.nix` in the root of Nixpkgs repository for information on how to use it.
`update.nix` offers several modes for selecting packages to update, and it will execute update scripts for all matched packages that have an `updateScript` attribute.

Update scripts will be run inside the [Nixpkgs development shell](../shell.nix), providing access to some useful tools for CI.
Furthermore each update script will be passed the following environment variables:

- [`UPDATE_NIX_NAME`] – content of the `name` attribute of the updated package
- [`UPDATE_NIX_PNAME`] – content of the `pname` attribute of the updated package
- [`UPDATE_NIX_OLD_VERSION`] – content of the `version` attribute of the updated package
- [`UPDATE_NIX_ATTR_PATH`] – attribute path the `update.nix` discovered the package on (or the package's specified `attrPath` when available).
  Example: `pantheon.elementary-terminal`

> [!Note]
> An update script will be usually run from the root of the Nixpkgs repository, but you should not rely on that.
> Also note that `update.nix` executes update scripts in parallel by default, so you should avoid running `git commit` or any other commands that cannot handle that.

While update scripts should not create commits themselves, `update.nix` supports automatically creating commits when running it with `--argstr commit true`.
If you need to customize commit message, you can have the update script implement the `commit` feature.

### Supported features
[update-script-supported-features]: #supported-features

- `commit`

  This feature allows update scripts to *ask* `update.nix` to create Git commits.

  When support of this feature is declared, whenever the update script exits with `0` return status, it is expected to print a JSON list containing an object described below for each updated attribute to standard output.
  Example:

  ```json
  [
    {
      "attrPath": "volume_key",
      "oldVersion": "0.3.11",
      "newVersion": "0.3.12",
      "files": [
        "/path/to/nixpkgs/pkgs/development/libraries/volume-key/default.nix"
      ]
    }
  ]
  ```
  :::

  When `update.nix` is run with `--argstr commit true`, it will create a separate commit for each of the objects.