How to Convert PDFs to Dark Mode in Python Without Ruining Photos

If you have ever tried to read a white-background PDF in bed with the lights off, you already know the problem: the page glows like a flashlight in your face. Most PDF viewers now offer some kind of “night mode,” but it only changes how the viewer displays the file on your screen. The PDF itself is unchanged, so the moment you open it somewhere else, a printer, a different app, a colleague’s laptop, it is back to a bright white page.

In this tutorial you will build a small Python command-line tool that actually rewrites a PDF’s pixels: light backgrounds become dark, dark text becomes light, and the file itself is dark from then on, no matter where you open it. Along the way you will hit the three mistakes almost everyone makes the first time they try this (a file that balloons to megabytes, a document that is no longer searchable, and photos that turn into ugly camera negatives), and you will fix each one with real, tested code.

You do not need any prior experience with PDF internals. You do need to be comfortable with basic Python: functions, loops, and running scripts from a terminal.

What You Will Build and Why It Matters

“Dark mode for a PDF” really means one specific, mechanical thing: take every pixel on every page and flip its brightness. A pixel that was almost white becomes almost black, and vice versa. Do that consistently across a page and a bright white background turns into a comfortable dark gray or black, while black text turns light and stays perfectly readable.

The tool you will build takes any PDF as input and produces a new PDF with every page color-inverted. It also does something most quick tutorials skip: it detects the actual photographs embedded in the document and leaves those alone, so a real photo does not come out looking like an X-ray. By the end, you will understand exactly why that second part is necessary, because you will see the broken version first.

Prerequisites

• A computer running Windows, macOS, or Linux. Every command below was tested on Windows with Python 3.13.14, but nothing in this tutorial is Windows-specific.
• Python 3.10 or newer, with pip available. Check with python --version.
• Basic command-line comfort: you should know how to create a folder and run a script from a terminal.
• No prior PDF, image-processing, or NumPy experience is assumed. Every concept is explained the first time it appears.

Step 1: Set Up a Python Environment

Start in a fresh project folder and create an isolated virtual environment. This keeps the libraries this project needs separate from anything else on your system.

mkdir pdf-dark-mode
cd pdf-dark-mode
python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate   # macOS or Linux

Now install the three libraries this project uses:

pip install pymupdf pillow numpy

Here is what that produced when this tutorial was written and tested:

Successfully installed numpy-2.5.1 pillow-12.3.0 pymupdf-1.28.2

Three libraries, three jobs:

• PyMuPDF (imported as pymupdf) opens PDFs, renders pages to images, and writes new PDFs back out.
• Pillow (imported as PIL) converts raw pixel data into standard image formats like PNG.
• NumPy gives you a fast array type so you can transform millions of pixel values with one line of code instead of a slow Python loop.

A Quick Naming Gotcha

Almost every older PyMuPDF tutorial you will find online starts with import fitz. That used to be the library’s only name. If you type that today, on the current release, you will get a real warning printed to your terminal:

warning: The `fitz` API is deprecated and will be removed in future. Use `import pymupdf` instead.

The project’s own tutorial confirms this directly: “Newer versions use pymupdf instead, and offer fitz as a fallback so that old code will still work.” Use import pymupdf throughout this tutorial (and in any new code you write) so you are not relying on a fallback that is explicitly scheduled for removal.

Step 2: Understand How PDF Rendering Actually Works

Why You Cannot Just “Invert a PDF” Directly

A PDF page is not a grid of pixels. It is a set of drawing instructions: “draw this line of text in this font at this position,” “fill this rectangle with this color.” There is no single “color” value sitting in the file that you could just flip. To invert colors, you first have to turn those instructions into an actual grid of pixels, a process called rasterizing, then flip every pixel, then save that grid of pixels back into a new PDF page. Keep that three-step shape in mind: render, transform, rebuild. Everything in this tutorial is one of those three steps.

Points, Pixels, and DPI

PDF page dimensions are measured in points, where 72 points equal one inch, regardless of how many pixels you eventually render. When you rasterize a page, you choose a resolution in DPI (dots per inch) that determines how many pixels you get per inch of page. A page rendered at 72 DPI produces one pixel per point; a page rendered at 144 DPI produces four times as many pixels (twice the width and twice the height), because pixel count grows with the square of the DPI increase. That relationship is the root cause of the file-size problem you will measure in Step 6.

PyMuPDF expresses this as a zoom factor you feed into a transformation matrix:

zoom = dpi / 72
matrix = pymupdf.Matrix(zoom, zoom)

At 150 DPI, zoom works out to about 2.08, meaning the page is rendered a little over twice as large, in pixels, as its point dimensions.

Step 3: Render a Page and Inspect Its Raw Pixels

Let’s render an actual page and look at what comes back. Create explore.py:

import pymupdf

doc = pymupdf.open("sample.pdf")
page = doc[0]

zoom = 150 / 72
pix = page.get_pixmap(matrix=pymupdf.Matrix(zoom, zoom), colorspace=pymupdf.csRGB, alpha=False)

print(f"pixmap size: {pix.width}x{pix.height}")
print(f"components per pixel (n): {pix.n}")
print(f"raw buffer length: {len(pix.samples)} bytes")
print(f"width * height * n = {pix.width * pix.height * pix.n}")

Running it against a simple one-page test PDF produced:

pixmap size: 834x625
components per pixel (n): 3
raw buffer length: 1563750 bytes
width * height * n = 1563750

Two details matter here. First, colorspace=pymupdf.csRGB together with alpha=False guarantees exactly 3 components per pixel (red, green, blue), with no transparency channel. alpha=False already happens to be PyMuPDF’s own default when the argument is left out entirely, but writing it explicitly is good practice: it documents, right there in the code, that the rest of this tutorial deliberately assumes 3 channels. If a page is ever rendered with alpha=True instead, pix.n becomes 4, and the simple 255 - arr inversion in the next step will happily flip that fourth (transparency) value too, along with red, green, and blue. Stick to alpha=False throughout this tutorial: mixing a 4-component array into the mode="RGB" conversion in Step 5 does not raise a clean error, it quietly produces the wrong image, which is a worse trap than a crash because nothing tells you it happened. Second, notice that the buffer length exactly equals width times height times n. According to PyMuPDF’s own documentation, samples is “the color…values for all pixels. It is an area of width * height * n bytes,” laid out in scanline order, row by row, left to right. That one fact is what lets you safely reshape the flat buffer into a proper 3D array in the next step.

Step 4: Invert the Colors With NumPy

Now reshape that flat buffer into a NumPy array and flip every value:

import numpy as np

arr = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, pix.n)
inverted = 255 - arr

dtype=np.uint8 tells NumPy that each value is one byte, 0 to 255. reshape turns the flat list of bytes into a 3D grid: rows, then columns, then the 3 color channels per pixel. 255 - arr is the entire algorithm: for every single byte in that grid, subtract it from 255. A pixel channel that was 255 (fully on) becomes 0 (fully off), and a channel that was 0 becomes 255. Do that to all three channels of a pixel and red (255, 0, 0) becomes cyan (0, 255, 255); white (255, 255, 255) becomes black (0, 0, 0). NumPy applies that subtraction to every one of the (in this example) 1,563,750 bytes in a single vectorized operation, which is why this approach is fast even on a large page.

Step 5: Rebuild a PDF From the Inverted Pixels

You now have a grid of inverted pixel values sitting in memory. To turn that back into a PDF page, convert it to a PNG image with Pillow, then place that image on a brand new PDF page sized to match the original:

import io
from PIL import Image

img = Image.fromarray(inverted, mode="RGB")
buf = io.BytesIO()
img.save(buf, format="PNG")

out = pymupdf.open()
new_page = out.new_page(width=page.rect.width, height=page.rect.height)
new_page.insert_image(new_page.rect, stream=buf.getvalue())
out.save("sample_inverted.pdf")

page.rect.width and page.rect.height are the original page’s point dimensions, not the pixel dimensions of your rendered image. That matters: it means the new page is the same physical size as the source page (still fits on the same paper, still opens at the same zoom level in a viewer), even though the image stretched across it was rendered at a different pixel resolution.

Verifying the Colors Actually Flipped

Do not take the math on faith. Render both the original and the new PDF the same way and sample specific pixels. A test page built with a white background, a solid red rectangle, and a solid blue circle produced this, sampled at identical coordinates before and after:

--- ORIGINAL ---
background:          (255, 255, 255)
red rectangle center: (255, 0, 0)
blue circle center:   (0, 0, 255)

--- INVERTED ---
background:          (0, 0, 0)
red rectangle center: (0, 255, 255)
blue circle center:   (255, 255, 0)

White became black. Red became cyan. Blue became yellow. Every value is exactly 255 minus the original, confirming the transformation did what Step 4 said it would.

Step 6: Watch Your DPI, or Your File Will Balloon

Here is the first real-world trap. Rasterizing a page and re-saving it as an embedded image is fundamentally less space-efficient than the vector instructions a normal PDF uses, and the effect gets dramatically worse as DPI increases. Running the same one-page test document (which already contains one embedded photo) through the inversion pipeline at four different DPI settings produced these output file sizes:

DPI   72:    528,564 bytes
DPI  100:  1,018,974 bytes
DPI  150:  2,285,561 bytes
DPI  300:  9,125,250 bytes

original source PDF: 184,125 bytes

Going from 150 to 300 DPI roughly quadrupled the file size, exactly as Step 2 predicted: doubling the DPI doubles both width and height in pixels, so the total pixel count, and roughly the file size, goes up by a factor of four. For a document you plan to read on a phone or tablet screen, 120 to 150 DPI is already sharper than the screen can usually distinguish. Reach for 300 DPI only if you actually intend to print the result, and expect the file size penalty when you do.

Step 7: You Will Lose Selectable Text (and Sometimes That’s Fine)

Here is the second trap, and it is easy to miss because the output still looks perfect. Extract text from the original PDF and then from the inverted one:

import pymupdf

for name in ["sample.pdf", "sample_inverted.pdf"]:
    doc = pymupdf.open(name)
    print(f"{name}: {doc[0].get_text()!r}")

sample.pdf: 'Hello Dark Mode\n'
sample_inverted.pdf: ''

The original page has a real text layer, so PyMuPDF can extract “Hello Dark Mode” from it directly. The inverted page has no text layer at all, because Step 5 replaced the entire page with a single flattened image. Visually the word “Hello” is still right there and perfectly legible to a human, but there is no longer any actual text object behind it: you cannot select it, search for it, copy and paste it, or have a screen reader read it aloud.

Whether that matters depends entirely on what you are going to do with the file. For a personal copy you intend to read once on your own phone at night, it is a completely reasonable trade-off. For a document you plan to archive, share for others to search, or that needs to stay accessible to screen-reader users, it is not, and you should keep the original file alongside the dark-mode copy rather than replacing it.

Step 8: Stop Naive Inversion From Turning Photos Into Negatives

The third trap is the most visually obvious once you see it. Build a test page with a headline, a photograph, and a caption, then run the naive inverter from Step 5 on it. Sampling a pixel from inside the photo, before and after, tells the story:

PHOTO center pixel
  original:       (191, 89, 127)
  naive inverted: (64, 166, 128)

That is exactly what Step 4’s math predicts (255 minus each channel), and that is precisely the problem: a warm sunset-toned photo comes out looking like a color-negative film strip. Inverting brightness makes sense for a white page with black text. It does not make sense for a photograph, where the actual colors are the point.

Finding the Image Regions on a Page

PyMuPDF can tell you exactly where embedded images sit on a page, in the same point-based coordinate system as the page itself:

for img_info in page.get_image_info():
    print(img_info["bbox"])

[30.0, 60.0, 330.0, 260.0]

That is a bounding box: left, top, right, and bottom, in points, matching exactly where the image was placed on the page.

Protecting Those Regions From Inversion

The fix is to invert the whole page as before, then paste the original, uninverted pixels back over each image’s bounding box. Converting the box from points to pixels uses the same zoom factor you already used to render the page, which is exactly why Step 2 introduced that relationship:

for img_info in page.get_image_info():
    x0, y0, x1, y1 = img_info["bbox"]
    px0, py0 = max(0, int(x0 * zoom)), max(0, int(y0 * zoom))
    px1, py1 = min(pix.width, int(x1 * zoom)), min(pix.height, int(y1 * zoom))
    if px1 > px0 and py1 > py0:
        inverted[py0:py1, px0:px1] = arr[py0:py1, px0:px1]

arr is the original, un-inverted pixel grid from Step 3. This line copies that original region directly on top of the corresponding rectangle in the inverted grid, after the full-page inversion already happened, so the photo’s rectangle ends up holding its true, original colors while everything around it (background and text) stays inverted. The max and min calls simply keep the box from running off the edge of the page if an image is placed slightly outside its bounds.

Proving It Worked

Sampling the same photo pixel and a background pixel from the corrected output confirms the fix:

PHOTO center pixel [row,col]
  original:        (191, 89, 127)
  naive inverted:  (64, 166, 128)
  smart inverted:  (191, 89, 127)

BACKGROUND pixel [row,col]
  original:        (255, 255, 255)
  naive inverted:  (0, 0, 0)
  smart inverted:  (0, 0, 0)

The photo pixel in the “smart” output matches the original exactly, while the background pixel is still correctly inverted to black. The page gets its dark background without the photo turning into an X-ray.

Step 9: Put It All Together Into a Reusable Script

Here is the complete, working command-line tool, combining every piece from Steps 3 through 8 into one file, pdf_dark_mode.py:

#!/usr/bin/env python3
"""Invert PDF page colors for dark-mode reading, without turning embedded photos into negatives."""
import argparse
import io
import time

import numpy as np
import pymupdf
from PIL import Image


def invert_pdf(src_path, out_path, dpi=150, preserve_images=True):
    src = pymupdf.open(src_path)
    out = pymupdf.open()
    zoom = dpi / 72
    matrix = pymupdf.Matrix(zoom, zoom)

    for page_number, page in enumerate(src):
        pix = page.get_pixmap(matrix=matrix, colorspace=pymupdf.csRGB, alpha=False)
        arr = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, pix.n)
        inverted = 255 - arr

        if preserve_images:
            for img_info in page.get_image_info():
                x0, y0, x1, y1 = img_info["bbox"]
                px0, py0 = max(0, int(x0 * zoom)), max(0, int(y0 * zoom))
                px1, py1 = min(pix.width, int(x1 * zoom)), min(pix.height, int(y1 * zoom))
                if px1 > px0 and py1 > py0:
                    inverted[py0:py1, px0:px1] = arr[py0:py1, px0:px1]

        png_bytes = io.BytesIO()
        Image.fromarray(inverted, mode="RGB").save(png_bytes, format="PNG", optimize=True)

        new_page = out.new_page(width=page.rect.width, height=page.rect.height)
        new_page.insert_image(new_page.rect, stream=png_bytes.getvalue())
        print(f"  processed page {page_number + 1}/{len(src)}")

    out.save(out_path)
    src.close()
    out.close()


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("input", help="source PDF path")
    parser.add_argument("output", help="output PDF path")
    parser.add_argument("--dpi", type=int, default=150, help="render resolution (default: 150)")
    parser.add_argument("--no-preserve-images", action="store_true", help="invert photos too (naive mode)")
    args = parser.parse_args()

    t0 = time.time()
    invert_pdf(args.input, args.output, dpi=args.dpi, preserve_images=not args.no_preserve_images)
    print(f"done in {time.time() - t0:.2f}s -> {args.output}")


if __name__ == "__main__":
    main()

One detail worth understanding: np.frombuffer creates an array that is a read-only view directly over PyMuPDF’s own buffer, not a new copy of the data. Try to write into it directly, with something like arr[0, 0, 0] = 42, and NumPy refuses with ValueError: assignment destination is read-only. That is not a problem for this script, because the code never writes into arr, it only ever reads from it. The line inverted = 255 - arr does not modify arr in place; it computes an entirely new array and hands you a reference to that instead, which is why inverted is freely writable even though arr is locked. That distinction, a view that aliases existing memory versus an operation that allocates a fresh array, is worth understanding on its own, because it explains a lot of otherwise-confusing NumPy behavior beyond just this one script.

Run it from the command line:

python pdf_dark_mode.py sample_with_photo.pdf output.pdf --dpi 150

  processed page 1/1
done in 0.04s -> output.pdf

To see the mistake from Step 8 on purpose, for comparison, add the naive flag:

python pdf_dark_mode.py sample_with_photo.pdf output_naive.pdf --no-preserve-images --dpi 100

Step 10: Verify the Whole Pipeline End to End

Before you trust this tool on documents you care about, check all of the following on a test file:

1. Open the output PDF in an actual viewer. The background should be dark and the former black text should now be light and still fully legible.
2. If the source document had photos and you left preserve_images enabled (the default), confirm they still look like normal photos, not negatives.
3. Check the output file size against your DPI choice using the numbers from Step 6. If a short document suddenly turned into tens of megabytes, your DPI is almost certainly higher than you need.
4. If you need to keep the document searchable or accessible, keep the original file. Do not treat the inverted copy as a replacement, per Step 7.
5. Run it against a multi-page document, not just a single page, and confirm the page count and page order in the output match the input.

Common Mistakes and Gotchas

• Typing import fitz out of habit. It still works today as a fallback, but current PyMuPDF (1.28.2 as of this writing) prints its own deprecation warning and recommends import pymupdf instead.
• Passing alpha=True without meaning to. This pipeline deliberately stays at alpha=False (already PyMuPDF’s own default, but written explicitly here for clarity) so every pixel has exactly 3 components. Switch to alpha=True and pix.n becomes 4; feeding that 4-component array into the mode="RGB" conversion from Step 5 does not raise an error, it silently produces a corrupted image, confirmed directly by comparing the pixel bytes before and after the conversion.
• Choosing 300 DPI “to be safe.” As Step 6 measured directly, that is roughly 4 times the file size of 150 DPI for the same page, with no visible benefit on a typical screen.
• Assuming the output is still searchable. It is not, by design of this technique. Step 7 showed the extracted text going from a real sentence to an empty string.
• Using a different zoom factor for the image bounding boxes than the one used to render the page. Step 8’s point-to-pixel conversion only lines up because it reuses the exact same zoom value that produced pix. Render the page at one DPI and convert the boxes with a different one and the preserved photo regions will land in the wrong place.
• Running this on a password-protected PDF without authenticating first. Opening an encrypted PDF and calling get_pixmap() without unlocking it first raises ValueError: document closed or encrypted, confirmed directly against a test file encrypted with pymupdf.PDF_ENCRYPT_AES_256. Call doc.authenticate(password) right after pymupdf.open() and check that it returns a nonzero result before doing anything else with the document.

Next Steps

You now have a working, tested tool that inverts PDF colors for comfortable dark-mode reading while protecting embedded photos. A few directions to take it further:

• Add a check that skips pages that already look dark (for example, by sampling the average brightness before deciding whether to invert), so you can safely batch-process a folder of mixed documents without double-inverting anything.
• Process an entire directory of PDFs in one run instead of a single file at a time.
• Try a softer transform than a full mathematical inversion, such as mapping white to a dark gray instead of pure black, which some readers find easier on the eyes than a pure black background.
• Wrap the script in a small drag-and-drop desktop interface using a library like tkinter, which ships with Python and needs no extra installation.

Further reading: PyMuPDF’s own official tutorial and its Pixmap class reference cover the rendering API used throughout this tutorial in more depth.