Add PDF Backgrounds in Python

Add a Background Image to a PDF

Background images can be used to add a watermark, or other subtle design, to documents. In Aspose.PDF for Python via .NET, each PDF document is a collection of pages and each page contains a collection of artifacts. The BackgroundArtifact class can be used to add a background image to a page object.

This approach is useful when you need to place a decorative image behind the main PDF content without turning it into searchable document text.

The following code snippet shows how to add a background image to PDF pages using the BackgroundArtifact object with Python.

  1. Load the PDF document.
  2. Create a background artifact.
  3. Load the image file.
  4. Attach the artifact to a page.
  5. Save the updated document.

from os import path
from io import FileIO
import aspose.pdf as ap
import sys

def add_background_image_to_pdf(infile, imagefile, outfile):
    """Add a background image to a PDF document as an artifact."""
    with ap.Document(infile) as document:
        artifact = ap.BackgroundArtifact()
        artifact.background_image = FileIO(imagefile, "rb")
        document.pages[1].artifacts.append(artifact)
        document.save(outfile)

Add a Background Image with Opacity to a PDF

Add a semi-transparent background image to a PDF page using Aspose.PDF for Python.

By applying opacity, the background image becomes partially transparent, allowing the original page content (text, images, etc.) to remain clearly visible. This is especially useful for:

  • Watermarks
  • Branding overlays
  • Subtle design enhancements

The background is added as an artifact, ensuring it stays behind all page content.

  1. Load the PDF document.
  2. Create a background artifact.
  3. Load the image file.
  4. Set the opacity level.
  5. Attach the artifact to a page.
  6. Save the updated document.

from os import path
from io import FileIO
import aspose.pdf as ap
import sys

def add_background_image_with_opacity_to_pdf(infile, imagefile, outfile):
    """Add a background image with opacity to a PDF document as an artifact."""
    with ap.Document(infile) as document:
        artifact = ap.BackgroundArtifact()
        artifact.background_image = FileIO(imagefile, "rb")
        artifact.opacity = 0.5
        document.pages[1].artifacts.append(artifact)
        document.save(outfile)

Add a Background Color to a PDF

Apply a solid background color to a PDF page using Aspose.PDF for Python.

  1. Load the PDF document.
  2. Create a background artifact.
  3. Set the background color.
  4. Attach the artifact to a page.
  5. Save the updated document.

from os import path
from io import FileIO
import aspose.pdf as ap
import sys

def add_background_color_to_pdf(infile, outfile):
    """Add a solid color background to a PDF document as an artifact."""
    with ap.Document(infile) as document:
        artifact = ap.BackgroundArtifact()
        artifact.background_color = ap.Color.dark_khaki
        document.pages[1].artifacts.append(artifact)
        document.save(outfile)

Remove Background from a PDF

Remove background artifacts from a PDF page using Aspose.PDF for Python. Backgrounds in PDFs are often stored as artifacts, and this method selectively identifies and removes only those artifacts that are classified as background elements.

  1. Load the PDF document.
  2. Access page artifacts.
  3. Filter background artifacts.
  4. Collect background elements.
  5. Delete background artifacts.
  6. Save the updated document.

from os import path
from io import FileIO
import aspose.pdf as ap
import sys

def remove_background(infile, outfile):
    with ap.Document(infile) as document:
        backgrounds = [
            artifact
            for artifact in document.pages[1].artifacts
            if artifact.type == ap.Artifact.ArtifactType.PAGINATION
            and artifact.subtype == ap.Artifact.ArtifactSubtype.BACKGROUND
        ]

        for background in backgrounds:
            document.pages[1].artifacts.delete(background)

        document.save(outfile)
Add Bates Numbering to PDF in Python Add Watermarks to PDF in Python