Frequently Asked Questions
- Can I specify a different PDF in the default viewer?
- Can I load a PDF from another server (cross domain request)?
- Which browsers/environments are supported?
- Which browsers have extensions (and where can I find install procedures)?
- Reasons for the Error:
The API version "a.b.c" does not match the Worker version "x.y.z"? - I know JavaScript and want to contribute to the project. How do I start?
- Is it possible to add annotations to a PDF?
- What are the PDF.js keyboard shortcuts?
- The PDF.js files are too big. Is it possible to obtain minified versions of the JS files?
- Is there a pre-built version PDF.js available?
- What is the ECCN for PDF.js?
- PDF.js does not render my files right. Can I report an issue?
- I know that my PDFs are corrupted. Will PDF.js attempt to display it?
- I have a really great idea. Where is the best place to record it?
- I'm developing a custom solution based on PDF.js core library. Can you help me?
- I want to render all 100 pages in a document at a high resolution. Is it a good idea?
- PDF.js is fetching the entire PDF file from a server. Can it fetch only the required portions for rendering?
- What is the latest stable version of PDF.js?
- What types of PDF files are slow in PDF.js? Can I optimize a PDF file to make PDF.js faster?
You can modify the defaultUrl app option in the web/app_options.js file or you can append the ?file= query string to the viewer URL, e.g. http://mozilla.github.com/pdf.js/web/viewer.html?file=compressed.tracemonkey-pldi-09.pdf. In the latter case, the PDF path/URL must be encoded using encodeURIComponent().
The viewer can be started without any PDF loaded by setting the defaultUrl app option to an empty string or by using the ?file= query string without any location specified. Use PDFViewerApplication.open({ url: file }); to load the PDF file later.
You can use raw binary data to open a PDF document: use Uint8Array instead of URL in the PDFViewerApplication.open call. If you have base64 encoded data, please decode it first -- not all browsers have atob or data URI scheme support. (The base64 conversion operation uses more memory, so we recommend delivering raw PDF data as typed array in first place.)
Not by default, but it is possible. PDF.js runs with the same permissions as any other JavaScript code, which means it cannot do cross origin requests (see Same origin policy and an example). There are some possible ways to get around this such as using CORS (see also unsafe headers issue and Access-Control-Expose-Headers issue) or setting up a proxy on your server that will feed PDF.js the PDF file (example: https://github.com/mozilla/pdf.js/issues/1000#issuecomment-133756244). Please notice that generic/demo viewer blocks this functionality if deployed not on mozilla.github.io domain to avoid content spoofing (see https://github.com/mozilla/pdf.js/pull/6916).
By default we produce a non-translated/non-polyfilled build, intended for the latest browsers. However, we also provide a translated/polyfilled build for older browsers in a separate bundle (with a legacy suffix).
The objective is to support all HTML5 compliant browsers, but since feature support varies per browser/version our support for all PDF features varies as well. If no version is indicated, then the latest desktop/mobile versions are implied.
| Browser/environment | Supported | Automated testing | Notes |
|---|---|---|---|
| Firefox | Yes | Windows/Linux | |
| Chrome | Yes | Windows/Linux |
| Browser/environment | Supported | Automated testing | Notes |
|---|---|---|---|
| Firefox ESR+ | Yes | None | |
| Chrome 98+ | Yes | None | |
| Opera | Yes | None | |
| Edge | Yes | None | Only the Chromium-based version. |
| Safari 16.4+ | Mostly | None | Some missing features/defects have been reported, but no problems in general. |
| Node.js 18+ | Mostly | Limited | Some missing features, but no problems in general. |
The Chromium extension is maintained by a PDF.js contributor. To install the Chromium extension, please refer to the README.
The Firefox extension is not supported and marked as disabled for Firefox versions 35 and up. PDF.js is part of Firefox since version 19. The extension is mostly used by developers and for bringing a newer version of the PDF.js library to an older Firefox version. Users should uninstall the extension, revert the pdfjs.disabled configuration setting and set the Options -> Applications selection for PDF documents to the internal viewer to continue viewing PDF files with PDF.js in Firefox.
When using the PDF.js library, it's necessary to use the exact same version of the pdf.js and pdf.worker.js files since otherwise things are not guaranteed to work correctly. In order to prevent bugs, the library will thus throw the aforementioned Error if there's a version mismatch.
Possible reasons for this Error include (but may not be limited to):
- Updating to a new version of the PDF.js library, and the old
pdf.worker.jsfile being cached in the browser. Usually clearing the browser cache, and then refreshing the page, should help in this case. - Including the
pdf.jsfile locally in your project, but loading thepdf.worker.jsfile from a CDN. In this case, please ensure that you are actually loading the corresponding version of thepdf.worker.jsfile from the CDN.
Finally, please note that the version number can always be found inside of the distributed files, such as e.g. pdf.js and pdf.worker.js; search for pdfjsVersion in order to find it.
First, you need to prepare your fork and setup the development environment. Don't forget to read the Contributing page. Second, make yourself familiar with the PDF format and PDF.js internals. Third, if you don't already have a certain issue you want to fix, choose one from the open issues labeled 5-good-beginner-bug. Last, submit a pull request for the review. During any part of the process we recommend communicating with the PDF.js team in the Matrix room if you have questions or need to find a reviewer.
PDF.js is designed for reading PDF files and supports rendering annotations for viewing, but also supports adding annotations using a subset of the possible annotation types.
The Home, End, Page up, Page down and all arrow keys can be used to navigate the document. Moreover, the following navigation shortcuts exist:
- Next page: n, j, Space bar (presentation mode only), Enter (presentation mode only) or left click (presentation mode only)
- Previous page: p, k, Shift + Space bar (presentation mode only), Shift + Enter (presentation mode only) or Shift + left click (presentation mode only)
User interface buttons or ctrl + mouse wheel can be used to change the zooming level, but keyboard shortcuts are also available:
- Zoom in: ctrl + +, ctrl + =
- Zoom out: ctrl + -
- Restore normal zoom: ctrl + 0
- Rotate the document clockwise: r
- Rotate the document counterclockwise: shift + r
- Activate presentation mode: ctrl + alt + p
- Enable the hand tool: h
- Enable the text selection tool: s
- Move focus to the 'go to page' box: ctrl + alt + g
- Find text in the document: ctrl + f
- Find next occurrence of text in the document: ctrl + g
- Find previous occurrence of text in the document: shift + ctrl + g
- Download the document: ctrl + s
- Print the document: ctrl + p
- Open a file: ctrl + o
(replace ctrl with meta on some configurations)
- Use F4 to toggle the visibility of the sidebar.
- After showing the sidebar, click on the "Show document outline" button (
) to show the document outline (if the PDF file has one).
- Nested outline items can be expanded/collapsed by clicking on the triangles at the left of an item.
- To expand/collapse all items under the selected item, press Shift while clicking on the triangle.
- Double-click on the "Show document outline" button (
) to show the document outline (if the PDF file has one).You can build a minified version of PDF.js using the following command:
npx gulp minified
We use Terser to minify the JS files. It is known that other minifiers might break PDF.js code if advanced options are used (see #710 or #2479). It's safe to use minifiers, such as Google Closure Compiler, in whitespace/comments removal mode. If you are not using npx gulp minified, please note that you must configure the minifier to keep original class/function names intact; otherwise the build is not guaranteed to work correctly.
Yes. Refer to http://mozilla.github.io/pdf.js/getting_started/ and https://github.com/mozilla/pdf.js/wiki/Setup-PDF.js-in-a-website#official-releases for more details. Generic PDF.js library builds can be installed via NPM with npm install pdfjs-dist.
PDF.js is publicly available software not subject to the Export Administration Regulations (EAR) per EAR 734.3(b) and 734.7. Because PDF.js is not subject to the EAR it does not have an Export Control Classification Number (ECCN). Mozilla has completed the notification for PDF.js publicly available encryption source code per EAR 742.15(b).
Yes. The issues are used to track both bugs filed by users and specific work items for developers. Try to file one issue per problem observed.
Please specify valid title (e.g. "Glyph spacing is incorrect" instead of "PDF.js does not work") and provide more details about the issue: link to the PDF, location in the PDF, screenshot, browser version, operating system, PDF.js version and JavaScript console warning/error messages. The issues that do not have enough details provided will be closed as invalid/incomplete.
Yes. PDF.js will attempt to recover usable PDF data (pages, content or fonts) and display the document. Please report the issue (see above) and we will take a look.
You can contact the developers in our Matrix room.
The issue tracking system is designed to record a single technical problem. A bug report is something a developer/contributor can work on. The GitHub issue tracker is not a good place for general, not well thought out or unworkable ideas. Most likely a discussion-type issue will not be addressed for a long time or closed as invalid.
We are glad to hear that and will try to help you, but first check the examples at https://github.com/mozilla/pdf.js#learning and search existing issues. If this does not help, please prepare short well-documented example that demonstrates the problem and make it accessible online on your website, JSBin, etc. before opening a new issue or contacting us in the Matrix room -- keep in mind that just code snippets won't help us troubleshoot the problem. Issues that do not provide enough details will be closed as invalid/incomplete (see reporting issue above).
Not really. You can count yourself: a letter page size is 816⨉1056px at 96DPI (and if you have a HiDPI display, multiply each dimension by window.devicePixelRatio, e.g., 2), so you will need a canvas that takes up 816⨉1056⨉4 = 3,446,784 bytes (don't forget to multiply that by e.g., 2⨉2 = 4 if it's a HiDPI display). This requires you to allocate 3.5Mb (or 14Mb) per page. You need a decent amount of memory to hold the 100 canvases, and it does not count the time that is spent on rendering them.
The demo viewer creates, renders, and holds canvases only for visible pages to reduce the amount of used memory. Our recommendation is to create and render only visible pages.
PDF.js is fetching the entire PDF file from a server. Can it fetch only the required portions for rendering?
Actually, PDF.js is doing just that. PDF is a complicated format; in most of the cases, the vital data of a PDF document is located at the end. Depending on browser support and on what web server returns the HTTP Range Requests headers, PDF.js may automatically start using HTTP Range Requests to fetch not-yet-loaded portions of a PDF needed for rendering visible pages, so a document can be rendered without fully loading it.
PDF.js is a general-purpose library to parse and render PDFs. It is included in a number of projects such as Firefox, a Chromium extension, et cetera. We are recording changes to the library with GitHub pull requests. The changelog is also available from the Git log.
The version number consists of three digits: the major release number, minor release number and build number. Before version 1.2, the major and minor numbers were selected when some major milestone was reached. Currently, we are using semantic versioning, where a major version release means that we can introduce API-breaking changes and a minor version release indicates added functionality and backwards compatible changes. The build number is incremented by one each time a new commit is pushed to the master branch.
We are moving fast and trying to land as much good stuff as we can review and test. The generic viewer always contains the latest PDF.js build and is available for testing.
We regularly (usually weekly or bi-weekly) push the library to the Firefox Nightly channel. To promote the latest beta to a stable release, we listen for feedback (via GitHub, Bugzilla or Matrix) from the users and projects that use the library. If no critical issues (e.g. a build is unusable, major regressions, et cetera) appeared, we promote the build to stable. Otherwise we fix the issues and create a new beta release.
Typically, PDFs with a smaller file size will be rendered faster and it depends on how big a single page is. The amount of pages does not affect the performance. It's essential that you optimize your documents for the web. See Optimize a PDF from Adobe's website for more information. There are more improvement techniques that we can suggest:
- Avoid using high resolution images -- 150 dpi resolution for scanned images shall be enough for screens, especially for low powered devices;
- Try to use JPEG encoding for color images/photos in RGB colorspace when possible;
- Avoid using expensive compositions/effects such as transitions/masking -- flatten transparency;
- Avoid using PDF generators (or don't create content) that produce ineffective PDF output (e.g. LibreOffice creates a lots of tiny images for vector elements/pictures it does not understand);
- If there is such a setting, use web-optimized PDF output / linearization;
- Fix or don't produce corrupted PDFs that do not conform to the PDF32000 specification.