imagemagick-cli: ImageMagick CLI Wrapper for Node.js

0.5.0 · active · verified Wed Apr 22

This package, `imagemagick-cli`, provides a robust and platform-independent Node.js interface for executing ImageMagick command-line tools. Currently at version 0.5.0, it differentiates itself by safely handling system-specific nuances, most notably mitigating the "Windows convert issue" where the `convert` command can conflict with a built-in Windows utility. It offers cross-platform compatibility, tested and verified across macOS, Linux, and Windows, supporting both ImageMagick 6 and 7 installations. The library is designed to wrap existing CLI tools, focusing on reliable execution rather than reimplementing ImageMagick's functionality in JavaScript. Releases are generally infrequent, driven by the need to address compatibility issues or improve stability.

Common errors

```
Error: Command failed: convert -version (or similar command)
```
cause The underlying ImageMagick executable (e.g., `convert`, `magick`) could not be found or executed, or it returned a non-zero exit code. This commonly indicates that ImageMagick is not installed on the system or is not configured in the system's PATH environment variable.

fix Verify that ImageMagick is installed on your system and its executable directory is included in your system's PATH. On Windows, also confirm there are no conflicts with the built-in `convert.exe` by trying `magick convert -version` in CMD.
```
imagemagickCli.getVersion() resolves to null
```
cause The library attempted to determine the installed ImageMagick version but could not find a callable ImageMagick executable or parse its version output. This typically means ImageMagick is either not installed or not properly accessible in the system PATH.

fix Install ImageMagick on your system and ensure it's correctly configured in the system PATH. You can often debug by trying `convert -version` or `magick -version` directly in your terminal.
```
Error: spawnSync imagemagick ENOENT (or similar for 'magick' or 'convert')
```
cause Node.js's underlying `spawnSync` or `spawn` function could not locate the specified ImageMagick executable. This is a direct indication that the command isn't available in the system's execution path.

fix Ensure ImageMagick is installed and that its installation directory (containing `convert.exe`, `magick.exe`, etc.) is correctly added to your system's PATH environment variable. Restart your terminal or IDE after modifying PATH.

Warnings

gotcha This library acts as a wrapper for the ImageMagick CLI tools. ImageMagick itself must be pre-installed on the operating system (e.g., via Homebrew, apt, or direct download) for this package to function. It does not bundle ImageMagick binaries.
Fix: Install ImageMagick on your operating system. For example, on macOS: `brew install imagemagick`; on Ubuntu: `sudo apt-get install imagemagick`; on Windows, download from the official ImageMagick website.
gotcha On Windows, direct execution of the `convert` command from the system PATH can conflict with a built-in Windows utility. This library specifically addresses and mitigates this known 'Windows convert issue' by intelligently calling `magick convert` or similar. Bypassing this library's `exec` method for `convert` commands on Windows may lead to unexpected behavior or errors.
Fix: Always use `imagemagickCli.exec('convert ...')` (or `imagemagickCli.exec('magick convert ...')` for IM7) instead of attempting to spawn `convert` directly when working with ImageMagick commands on Windows.
gotcha Versions prior to `0.2.0` had known issues correctly handling ImageMagick installation paths containing spaces on Windows, which could lead to command execution failures even if ImageMagick was correctly installed.
Fix: Upgrade to `imagemagick-cli@0.2.0` or higher to resolve compatibility issues with ImageMagick paths containing spaces on Windows.

Install

npm install imagemagick-cli npm
yarn add imagemagick-cli yarn
pnpm add imagemagick-cli pnpm

Imports

imagemagickCli
```
const imagemagickCli = require('imagemagick-cli');
```
The library primarily exposes a CommonJS module. For ESM, consider using dynamic import or a transpiler as direct named imports may not be supported without configuration.
exec
wrong:
```
import { exec } from 'imagemagick-cli';
```
correct:
```
imagemagickCli.exec('command');
```
The `exec` method is a property of the default module export (the `imagemagickCli` object), not a named export. It returns a Promise that resolves with `stdout` and `stderr`.
getVersion
wrong:
```
import { getVersion } from 'imagemagick-cli';
```
correct:
```
imagemagickCli.getVersion();
```
The `getVersion` method is a property of the default module export. It returns a Promise that resolves with the detected ImageMagick version string or `null` if the version cannot be identified.

Quickstart

Demonstrates executing an ImageMagick command and retrieving its version using the `imagemagick-cli` wrapper, with error handling for common installation issues.

const imagemagickCli = require('imagemagick-cli');

async function checkImageMagick() {
  try {
    // Execute a simple ImageMagick command to get its version
    const { stdout, stderr } = await imagemagickCli.exec('convert -version');
    console.log(`ImageMagick convert command output:\n${stdout}`);
    if (stderr) {
      console.error(`ImageMagick convert stderr:\n${stderr}`);
    }

    // Use the dedicated getVersion method for convenience
    const version = await imagemagickCli.getVersion();
    if (version) {
      console.log(`Detected ImageMagick version via getVersion(): ${version}`);
    } else {
      console.warn('imagemagick-cli could not detect ImageMagick version via getVersion(). Ensure it is installed and in your system PATH.');
    }
  } catch (error) {
    console.error('Failed to execute ImageMagick command or detect version:', error.message);
    console.error('Please ensure ImageMagick is installed on your system and accessible in the PATH environment variable.');
  }
}

checkImageMagick();

view raw JSON →