Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fromPath
✓ import { fromPath } from 'pdf2pic';
✗ const fromPath = require('pdf2pic').fromPath;
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
✓ import { fromBuffer } from 'pdf2pic';
✗ import pdf2pic from 'pdf2pic'; // pdf2pic.fromBuffer
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
✓ import type { Pdf2picOptions } from 'pdf2pic';
✗ import { 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.
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);
}
Errors
Common errors & fixes
Error: spawn gm ENOENT
The GraphicsMagick or ImageMagick system executable is not found. It's either not installed or not configured correctly in the system's PATH.
fixInstall 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
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.
fixInstall 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
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.
fixEnsure 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
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.
fixAlways use named imports: `import { fromPath } from 'pdf2pic';`. If using CommonJS, use destructuring: `const { fromPath } = require('pdf2pic');`. Audit
Dependencies
gmrequiredThis is the primary Node.js interface pdf2pic uses to interact with the GraphicsMagick/ImageMagick system binary for image processing. GraphicsMagick or ImageMagick must be installed system-wide.
GraphicsMagick/ImageMagick (system-level)requiredEssential external software for image manipulation and conversion, required by pdf2pic. Must be installed and accessible in the system's PATH.
Ghostscript (system-level)requiredCrucial external software for rendering PDF documents into images, required by pdf2pic. Must be installed and accessible in the system's PATH.