{"id":17018,"library":"imagemagick-cli","title":"imagemagick-cli: ImageMagick CLI Wrapper for Node.js","description":"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.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/dwmkerr/node-imagemagick-cli","tags":["javascript","imagemagick","magick"],"install":[{"cmd":"npm install imagemagick-cli","lang":"bash","label":"npm"},{"cmd":"yarn add imagemagick-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add imagemagick-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"imagemagickCli","correct":"const imagemagickCli = require('imagemagick-cli');"},{"note":"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`.","wrong":"import { exec } from 'imagemagick-cli';","symbol":"exec","correct":"imagemagickCli.exec('command');"},{"note":"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.","wrong":"import { getVersion } from 'imagemagick-cli';","symbol":"getVersion","correct":"imagemagickCli.getVersion();"}],"quickstart":{"code":"const imagemagickCli = require('imagemagick-cli');\n\nasync function checkImageMagick() {\n  try {\n    // Execute a simple ImageMagick command to get its version\n    const { stdout, stderr } = await imagemagickCli.exec('convert -version');\n    console.log(`ImageMagick convert command output:\\n${stdout}`);\n    if (stderr) {\n      console.error(`ImageMagick convert stderr:\\n${stderr}`);\n    }\n\n    // Use the dedicated getVersion method for convenience\n    const version = await imagemagickCli.getVersion();\n    if (version) {\n      console.log(`Detected ImageMagick version via getVersion(): ${version}`);\n    } else {\n      console.warn('imagemagick-cli could not detect ImageMagick version via getVersion(). Ensure it is installed and in your system PATH.');\n    }\n  } catch (error) {\n    console.error('Failed to execute ImageMagick command or detect version:', error.message);\n    console.error('Please ensure ImageMagick is installed on your system and accessible in the PATH environment variable.');\n  }\n}\n\ncheckImageMagick();","lang":"javascript","description":"Demonstrates executing an ImageMagick command and retrieving its version using the `imagemagick-cli` wrapper, with error handling for common installation issues."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `imagemagick-cli@0.2.0` or higher to resolve compatibility issues with ImageMagick paths containing spaces on Windows.","message":"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.","severity":"gotcha","affected_versions":"<0.2.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Command failed: convert -version (or similar command)"},{"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.","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.","error":"imagemagickCli.getVersion() resolves to null"},{"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.","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.","error":"Error: spawnSync imagemagick ENOENT (or similar for 'magick' or 'convert')"}],"ecosystem":"npm","meta_description":null}