PDF to Image Conversion Utility

3.2.0 · active · verified Sun Apr 19

pdf2pic is a robust Node.js utility library designed for converting PDF documents into various image formats (like PNG, JPEG), base64 encoded strings, or raw image buffers. The current stable version is 3.2.0, with the project maintaining an active release cadence, frequently delivering patches and minor updates. A key differentiator of pdf2pic is its flexibility in output types and its ability to handle conversions from file paths, buffers, or base64 input. It acts as a wrapper around powerful external system dependencies: GraphicsMagick (or ImageMagick) for image processing and Ghostscript for PDF rendering. This design necessitates prior installation of these tools on the host system. The library ships with comprehensive TypeScript type definitions, enhancing the development experience for TypeScript users, and requires Node.js version 14 or higher.

Common errors

```
Error: spawn gm ENOENT
```
cause The GraphicsMagick or ImageMagick system executable is not found. It's either not installed or not configured correctly in the system's PATH.

fix Install GraphicsMagick or ImageMagick on your operating system (e.g., `sudo apt-get install graphicsmagick` on Debian/Ubuntu, `brew install graphicsmagick` on macOS). Verify its presence by running `gm -version` or `convert -version` in your terminal.
```
Error: spawn gs ENOENT
```
cause The Ghostscript system executable is not found. It's either not installed or not configured correctly in the system's PATH, which is crucial for PDF rendering.

fix Install Ghostscript on your operating system (e.g., `sudo apt-get install ghostscript` on Debian/Ubuntu, `brew install ghostscript` on macOS). Verify its presence by running `gs -version` in your terminal.
```
Error: Command failed: gm convert: No such file or directory
```
cause This error typically indicates that the PDF file path provided to `fromPath` is incorrect, the file does not exist at that location, or the file is not a valid PDF that GraphicsMagick can process.

fix Ensure the `filePath` argument points to a valid, accessible PDF file. Use an absolute path or carefully resolve relative paths. Check file permissions.
```
TypeError: (0 , pdf2pic__WEBPACK_IMPORTED_MODULE_0__.fromPath) is not a function
```
cause This Webpack or bundler error (or similar 'is not a function' errors) usually means an incorrect import style, attempting to use named exports as a default import, or misconfiguring module resolution.

fix Always use named imports: `import { fromPath } from 'pdf2pic';`. If using CommonJS, use destructuring: `const { fromPath } = require('pdf2pic');`.

Warnings

breaking Node.js 16 support was temporarily dropped in version 3.1.2, potentially causing issues for users on that Node.js version. It was re-added in version 3.1.3.
Fix: Users running Node.js 16 should ensure they are using pdf2pic@3.1.3 or a newer version to maintain compatibility. Avoid version 3.1.2.
gotcha pdf2pic relies heavily on external system dependencies: GraphicsMagick (or ImageMagick) and Ghostscript. These must be installed on the host system and be accessible in the system's PATH environment variable for the library to function correctly.
Fix: Before using pdf2pic, follow the installation instructions in the official documentation (e.g., `docs/gm-installation.md` on GitHub) to install GraphicsMagick/ImageMagick and Ghostscript for your operating system.
gotcha Older versions of pdf2pic (prior to 3.1.4) used an underlying `gm` dependency that contained a `cross-spawn` vulnerability. Upgrading is recommended for security.
Fix: Upgrade pdf2pic to version `3.1.4` or newer to ensure the underlying `gm` dependency is updated and the `cross-spawn` vulnerability is mitigated.
deprecated The `fs-extra` dependency was removed in version 3.0.1. While not directly breaking for standard use, any implicit reliance on `fs-extra` functionalities through `pdf2pic` in older versions might be affected.
Fix: If your application relied on `fs-extra` through `pdf2pic` (unlikely for typical usage), explicitly add `fs-extra` as a direct dependency to your project or refactor file system operations to use Node.js's native `fs` module.

Install

npm install pdf2pic npm
yarn add pdf2pic yarn
pnpm add pdf2pic pnpm

Imports

fromPath
wrong:
```
const fromPath = require('pdf2pic').fromPath;
```
correct:
```
import { fromPath } from 'pdf2pic';
```
The primary function to initiate conversion from a file path. pdf2pic primarily uses named exports. While CommonJS require() may still work, ESM imports are standard for Node.js >=14.
fromBuffer
wrong:
```
import pdf2pic from 'pdf2pic'; // pdf2pic.fromBuffer
```
correct:
```
import { fromBuffer } from 'pdf2pic';
```
Used when the PDF content is already in a Node.js Buffer. pdf2pic does not provide a default export; functions must be imported by name.
Pdf2picOptions
wrong:
```
import { Pdf2picOptions } from 'pdf2pic';
```
correct:
```
import type { Pdf2picOptions } from 'pdf2pic';
```
Imports the TypeScript type definition for configuration options. Using 'import type' ensures it's a type-only import, which is best practice for clarity and bundler optimization.

Quickstart

This quickstart demonstrates how to initialize pdf2pic from a file path, convert a specific page to an image file, and includes robust error handling for common issues like missing external dependencies. It also shows an example of converting all pages in a PDF document.

import { fromPath } from "pdf2pic";
import path from "path";
import { promises as fs } from 'fs';

// Ensure the output directory exists
const savePath = path.resolve("./images");
await fs.mkdir(savePath, { recursive: true });

// In a real application, provide a full, valid path to your PDF.
// For this example, ensure 'sample.pdf' exists in your project root.
const pdfFilePath = path.resolve("./sample.pdf");

const options = {
  density: 100,
  saveFilename: "converted_page",
  savePath: savePath,
  format: "png",
  width: 600,
  height: 600
};

const convert = fromPath(pdfFilePath, options);
const pageToConvertAsImage = 1;

try {
  const result = await convert(pageToConvertAsImage, { responseType: "image" });
  console.log(`Page ${pageToConvertAsImage} converted successfully.`);
  console.log(`Output: ${path.join(result.path, result.name)}`);
} catch (error) {
  console.error("Error converting PDF page:", error.message);
  // Provide detailed error messages for common prerequisites issues
  if (error.message.includes("gm ENOENT")) {
    console.error("GraphicsMagick/ImageMagick not found. Ensure it's installed and in PATH.");
    console.error("See: https://github.com/yakovmeister/pdf2image#prerequisites");
  } else if (error.message.includes("gs ENOENT")) {
    console.error("Ghostscript not found. Ensure it's installed and in PATH.");
    console.error("See: https://github.com/yakovmeister/pdf2image#prerequisites");
  }
}

// Optional: Example for converting all pages
try {
  console.log("\nAttempting to convert all pages...");
  // To run this, you must have a 'sample.pdf' in your project root.
  // For testing, consider using a small dummy PDF.
  const bulkResult = await fromPath(pdfFilePath, options).bulk(-1, { responseType: "image" });
  console.log(`Successfully converted ${bulkResult.length} pages.`);
} catch (error) {
  console.error("Error converting all PDF pages:", error.message);
}

view raw JSON →