{"id":11536,"library":"pdf2pic","title":"PDF to Image Conversion Utility","description":"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.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/yakovmeister/pdf2image","tags":["javascript","pdf-to-image","pdf-to-jpg","pdf-to-png","pdf","convert","image","pdf2img","pdf2pic","typescript"],"install":[{"cmd":"npm install pdf2pic","lang":"bash","label":"npm"},{"cmd":"yarn add pdf2pic","lang":"bash","label":"yarn"},{"cmd":"pnpm add pdf2pic","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This 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.","package":"gm","optional":false},{"reason":"Essential external software for image manipulation and conversion, required by pdf2pic. Must be installed and accessible in the system's PATH.","package":"GraphicsMagick/ImageMagick (system-level)","optional":false},{"reason":"Crucial external software for rendering PDF documents into images, required by pdf2pic. Must be installed and accessible in the system's PATH.","package":"Ghostscript (system-level)","optional":false}],"imports":[{"note":"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.","wrong":"const fromPath = require('pdf2pic').fromPath;","symbol":"fromPath","correct":"import { fromPath } from 'pdf2pic';"},{"note":"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.","wrong":"import pdf2pic from 'pdf2pic'; // pdf2pic.fromBuffer","symbol":"fromBuffer","correct":"import { fromBuffer } from 'pdf2pic';"},{"note":"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.","wrong":"import { Pdf2picOptions } from 'pdf2pic';","symbol":"Pdf2picOptions","correct":"import type { Pdf2picOptions } from 'pdf2pic';"}],"quickstart":{"code":"import { fromPath } from \"pdf2pic\";\nimport path from \"path\";\nimport { promises as fs } from 'fs';\n\n// Ensure the output directory exists\nconst savePath = path.resolve(\"./images\");\nawait fs.mkdir(savePath, { recursive: true });\n\n// In a real application, provide a full, valid path to your PDF.\n// For this example, ensure 'sample.pdf' exists in your project root.\nconst pdfFilePath = path.resolve(\"./sample.pdf\");\n\nconst options = {\n  density: 100,\n  saveFilename: \"converted_page\",\n  savePath: savePath,\n  format: \"png\",\n  width: 600,\n  height: 600\n};\n\nconst convert = fromPath(pdfFilePath, options);\nconst pageToConvertAsImage = 1;\n\ntry {\n  const result = await convert(pageToConvertAsImage, { responseType: \"image\" });\n  console.log(`Page ${pageToConvertAsImage} converted successfully.`);\n  console.log(`Output: ${path.join(result.path, result.name)}`);\n} catch (error) {\n  console.error(\"Error converting PDF page:\", error.message);\n  // Provide detailed error messages for common prerequisites issues\n  if (error.message.includes(\"gm ENOENT\")) {\n    console.error(\"GraphicsMagick/ImageMagick not found. Ensure it's installed and in PATH.\");\n    console.error(\"See: https://github.com/yakovmeister/pdf2image#prerequisites\");\n  } else if (error.message.includes(\"gs ENOENT\")) {\n    console.error(\"Ghostscript not found. Ensure it's installed and in PATH.\");\n    console.error(\"See: https://github.com/yakovmeister/pdf2image#prerequisites\");\n  }\n}\n\n// Optional: Example for converting all pages\ntry {\n  console.log(\"\\nAttempting to convert all pages...\");\n  // To run this, you must have a 'sample.pdf' in your project root.\n  // For testing, consider using a small dummy PDF.\n  const bulkResult = await fromPath(pdfFilePath, options).bulk(-1, { responseType: \"image\" });\n  console.log(`Successfully converted ${bulkResult.length} pages.`);\n} catch (error) {\n  console.error(\"Error converting all PDF pages:\", error.message);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.1.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.1.4"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<3.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The GraphicsMagick or ImageMagick system executable is not found. It's either not installed or not configured correctly in the system's PATH.","error":"Error: spawn gm ENOENT"},{"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.","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.","error":"Error: spawn gs ENOENT"},{"fix":"Ensure the `filePath` argument points to a valid, accessible PDF file. Use an absolute path or carefully resolve relative paths. Check file permissions.","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.","error":"Error: Command failed: gm convert: No such file or directory"},{"fix":"Always use named imports: `import { fromPath } from 'pdf2pic';`. If using CommonJS, use destructuring: `const { fromPath } = require('pdf2pic');`.","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.","error":"TypeError: (0 , pdf2pic__WEBPACK_IMPORTED_MODULE_0__.fromPath) is not a function"}],"ecosystem":"npm"}