# balena-preload

> Preload balena OS images with a user application container

Latest version **19.0.5** (published 2026-06-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install balena-preload
pnpm add balena-preload
yarn add balena-preload
bun add balena-preload
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 19.0.5 |
| Published | 2026-06-10 |
| First published | 2018-10-15 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^22.18.0 \|\| >= 24.0.0 |
| Dependencies | 8 |
| Unpacked size | 116.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 37 |
| Author | Balena Ltd |
| Maintainers | balena.io |
| Keywords | balena, balenaos, image, docker, container |

## Links

- npm: https://www.npmjs.com/package/balena-preload
- Repository: https://github.com/balena-io-modules/balena-preload
- Issues: https://github.com/balena-io-modules/balena-preload/issues
- npm.io page: https://npm.io/package/balena-preload

## Dependencies (8)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [tar-fs](https://npm.io/package/tar-fs.md) ^2.1.1
- [get-port](https://npm.io/package/get-port.md) ^3.2.0
- [dockerode](https://npm.io/package/dockerode.md) ^4.0.2
- [balena-sdk](https://npm.io/package/balena-sdk.md) ^23.0.0
- [node-cleanup](https://npm.io/package/node-cleanup.md) ^2.1.2
- [docker-progress](https://npm.io/package/docker-progress.md) ^5.0.0
- [compare-versions](https://npm.io/package/compare-versions.md) ^4.0.0

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 19.0.5 (latest) — 2026-06-10
- 19.0.6-build-renovate-pypi-sh-vulnerability-20b3dc807ff5481df9722748fe95115292c00556-1 (build-renovate-pypi-sh-vulnerability) — 2026-07-17
- 19.0.6-build-renovate-dockerode-5-x-423dee380ebba8364c80f0cc2e9a058c17cb7aa4-1 (build-renovate-dockerode-5-x) — 2026-06-10
- 19.0.5-build-renovate-alpine-3-24-d3e2be5abe462cd6abe8c27a33ecef427c9a246b-1 (build-renovate-alpine-3-24) — 2026-06-10
- 19.0.4-build-renovate-alpine-3-x-868ad0c60f6738d2cde7fc40d1a58dcc14b747ba-1 (build-renovate-alpine-3-x) — 2026-06-10
- 19.0.3-build-renovate-compare-versions-4-x-137d57f8da8a387f102ae3c7153b08007437d559-1 (build-renovate-compare-versions-4-x) — 2026-05-12
- 20.0.0-build-bump-typescript-to-6-0-2-f0b34bcabb994ad58a67ede1005982bf1b2c63de-1 (build-bump-typescript-to-6-0-2) — 2026-04-07
- 19.0.2-build-renovate-major-22-node-3371856c53e3c2cb84a20d5c5e314fdffc58fe68-1 (build-renovate-major-22-node) — 2026-02-19
- 19.0.1-build-add-npm-oidc-permissions-e0595aa5b4bc0d1ca031ca6a2c0d6cb3048b6eda-1 (build-add-npm-oidc-permissions) — 2026-02-19
- 19.0.0-build-sdk-23-c75eec79633cf4826e2cdb7b525a8128ea4cc067-1 (build-sdk-23) — 2026-02-10
- 18.0.5-build-bump-balena-sdk-89546d800e46bb26d4237b1da5b297d49b072c5c-1 (build-bump-balena-sdk) — 2025-08-07
- 18.0.4-build-fix-pip-edd39729cfdc630c95ee4b5c1dffdba3b459224d-1 (build-fix-pip) — 2025-05-21
- 18.0.3-build-renovate-sh-1-x-a1ad075baee7833286d10466683e0ccba6d4a6a1-1 (build-renovate-sh-1-x) — 2025-03-19
- 18.0.1-build-fix-sdk-major-bump-03f57f55472f147388756855b0a8fb423fd94d2b-1 (build-fix-sdk-major-bump) — 2025-03-04
- 18.0.0-build-update-balena-sdk-21-639fbf09a63414eeceaa3e678a79c31ebb9fa285-1 (build-update-balena-sdk-21) — 2025-03-04
- … 286 more at https://npm.io/package/balena-preload/versions

## README

# balena-preload
[![npm](https://img.shields.io/npm/v/balena-preload.svg?style=flat-square)](https://npmjs.com/package/balena-preload)
[![npm license](https://img.shields.io/npm/l/balena-preload.svg?style=flat-square)](https://npmjs.com/package/balena-preload)
[![npm downloads](https://img.shields.io/npm/dm/balena-preload.svg?style=flat-square)](https://npmjs.com/package/balena-preload)

Script for preloading balena OS images (`.img`) with a user application container.

Using this will allow images with supervisor version above 1.0.0 to run the user application without connectivity, and without the need to download the container.

## Warning

In order to preload images that use the overlay2 Docker storage driver (like
nvidia jetson tx2 for example), you need to load the `overlay` Linux module:

```sh
sudo modprobe overlay
```

For other images you will need to have the `aufs` module loaded.


## Deprecation

The standalone mode described below (balena-preload) is now deprecated.
It will be removed in a future release.
You should use [balena-cli](https://www.npmjs.com/package/balena-cli) instead.

Install [balena-cli](https://www.npmjs.com/package/balena-cli) and run
`balena help preload`.


## Install via [npm](https://npmjs.com)

```sh
$ npm install --global balena-preload
```

<!-- MarkdownTOC -->

- [Requirements](#requirements)
- [Known Issues](#known-issues)
    - [Speed Issues For Flasher Images on macOS](#speed-issues-for-flasher-images-on-macos)
    - [Version Compatibility](#version-compatibility)
    - [BTRFS Support](#btrfs-support)

<!-- /MarkdownTOC -->

## Requirements

- [Node](https://nodejs.org)
- [Docker](https://www.docker.com) tested on 1.12.6 and up but 17.04 or up is recommended especially on macOS, [docker-toolbox](https://www.docker.com/products/docker-toolbox) is not supported.
Older versions of balena-preload do support docker-toolbox, see [Version Compatibility](#version-compatibility) below.

### Issues

 If you encounter any problem, you can [open an issue](https://github.com/balena-io/balena-preload/issues)

## Known Issues

### Speed Issues For Flasher Images on macOS

Docker on macOS has [some speed issues with volumes](https://github.com/docker/for-mac/issues/77).
This makes this script slow, especially with Flasher Images.

### Version Compatibility

This version will only work for balena OS versions 1.2 and later.
For versions earlier than 1.2 you will need to checkout commit `5d6d4607bffc98acdf649ce5328e2079dfb9c3d9` of this repo and then follow the steps below. 

### BTRFS Support

Since Docker for Mac removed support for the BTRFS storage driver (see [docker/for-mac/issues/388](https://github.com/docker/for-mac/issues/388)), preloading images prior to balena OS 2.0 will require the older [Docker toolbox](https://docs.docker.com/toolbox/toolbox_install_mac/) setup with [VirtualBox](https://www.virtualbox.org/) to function properly.

---
_Source: https://npm.io/package/balena-preload · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._