# pkgs.portableService {#sec-pkgs-portableService}

`pkgs.portableService` is a function to create [Portable Services](https://systemd.io/PORTABLE_SERVICES/) in a read-only, immutable, `squashfs` raw disk image.
This lets you use Nix to build images which can be run on many recent Linux distributions.

::: {.note}
Portable services are supported starting with systemd 239 (released on 2018-06-22).
:::

The generated image will contain the file system structure as required by the Portable Services specification, along with the packages given to `portableService` and all of their dependencies.
When generated, the image will exist in the Nix store with the `.raw` file extension, as required by the specification.
See [](#ex-portableService-hello) to understand how to use the output of `portableService`.

## Inputs {#ssec-pkgs-portableService-inputs}

`portableService` expects one argument with the following attributes:

`pname` (String)

: The name of the portable service.
  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.

`version` (String)

: The version of the portable service.
  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.

`units` (List of Attribute Set)

: A list of derivations for systemd unit files.
  Each derivation must produce a single file, and must have a name that starts with the value of `pname` and ends with the suffix of the unit type (e.g. ".service", ".socket", ".timer", and so on).
  See [](#ex-portableService-hello) to better understand this naming constraint.

`description` (String or Null; _optional_)

: If specified, the value is added as `PORTABLE_PRETTY_NAME` to the `/etc/os-release` file in the generated image.
  This could be used to provide more information to anyone inspecting the image.

  _Default value:_ `null`.

`homepage` (String or Null; _optional_)

: If specified, the value is added as `HOME_URL` to the `/etc/os-release` file in the generated image.
  This could be used to provide more information to anyone inspecting the image.

  _Default value:_ `null`.

`symlinks` (List of Attribute Set; _optional_)

: A list of attribute sets in the format `{object, symlink}`.
  For each item in the list, `portableService` will create a symlink in the path specified by `symlink` (relative to the root of the image) that points to `object`.

  All packages that `object` depends on and their dependencies are automatically copied into the image.

  This can be used to create symlinks for applications that assume some files to exist globally (`/etc/ssl` or `/bin/bash`, for example).
  See [](#ex-portableService-symlinks) to understand how to do that.

  _Default value:_ `[]`.

`contents` (List of Attribute Set; _optional_)

: A list of additional derivations to be included as-is in the image.
  These derivations will be included directly in a `/nix/store` directory inside the image.

  _Default value:_ `[]`.

`squashfsTools` (Attribute Set; _optional_)

: Allows you to override the package that provides {manpage}`mksquashfs(1)`, which is used internally by `portableService`.

  _Default value:_ `pkgs.squashfsTools`.

`squash-compression` (String; _optional_)

: Passed as the compression option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.