> A common pattern is to use the [`nix-update-script`](../pkgs/by-name/ni/nix-update/nix-update-script.nix) attribute provided in Nixpkgs, which runs [`nix-update`](https://github.com/Mic92/nix-update):
>
> ```nix
> { stdenv, nix-update-script }:
> stdenv.mkDerivation {
>   # ...
>   passthru.updateScript = nix-update-script { };
> }
> ```
>
> For simple packages, this is often enough, and will ensure that the package is updated automatically by [`nixpkgs-update`](https://github.com/nix-community/nixpkgs-update) when a new version is released.
> The [update bot](https://nix-community.org/update-bot) runs periodically to attempt to automatically update packages, and will run `passthru.updateScript` if set.
> While not strictly necessary if the project is listed on [Repology](https://repology.org), using `nix-update-script` allows the package to update via many more sources (e.g. GitHub releases).

The `passthru.updateScript` attribute can contain one of the following:

- 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.

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`.