Registry / data / dataframe-image

dataframe-image

library0.2.7pypypi✓ verified 87d ago

dataframe-image is a Python library that enables embedding pandas DataFrames as images in PDF and Markdown files when converting from Jupyter Notebooks. It ensures DataFrames, including any applied styling, appear exactly as they do in a Jupyter Notebook, rather than as raw text or simple LaTeX tables. The library also provides functionality to export individual DataFrames as image files from Python scripts. It is actively maintained, with version 0.2.7 being the current release.

data serialization

pip install dataframe-image

github ↗package ↗

INSTALL

IMPORT

SIG · DATAFRAME-IMAGE

dataframe-image

datapythonv0.2.7

Install

18.1s avg

Import

3155ms

Disk

323MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 3.272s · 251.6MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 18.1s · import 3.038s · 382MB

323MB installed

● package 323MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dataframe_image

✓ import dataframe_image as dfi

export

✓ dfi.export(...)

✗ dataframe_image.export(...)

Commonly imported as 'dfi' alias for brevity and convention.

This quickstart demonstrates how to create a styled pandas DataFrame and export it as a PNG image using `dataframe_image.export`. The `dfi.export` function captures the DataFrame's appearance, including styling, and saves it to the specified file.

import pandas as pd import numpy as np import dataframe_image as dfi # Create a sample DataFrame df = pd.DataFrame(np.random.randn(6, 4), columns=list('ABCD')) # Apply some styling df_styled = df.style.background_gradient(cmap='Blues').set_caption('My Styled DataFrame') # Export the styled DataFrame as a PNG image dfi.export(df_styled, 'styled_dataframe.png') print("Styled DataFrame exported to styled_dataframe.png")

Debug

Known issues

breakingThe default browser backend for image conversion changed to Playwright in v0.2.7. If you were relying on the previous Chrome-based default without explicit configuration, you might need to install 'dataframe_image[playwright]' or explicitly set 'table_conversion' to 'chrome' (if Chrome is installed) or 'selenium' (for Firefox).

fix

Explicitly install 'pip install "dataframe_image[playwright]"' or configure `table_conversion='chrome'` or `table_conversion='selenium'` in your export/convert calls. Ensure the necessary browser (Chromium/Firefox) is installed if using browser-based conversion.

affects: >=0.2.7

breakingVersion 0.2.4 was the last to use `setup.py` for installation and allowed direct file insertion into Jupyter directories. Subsequent versions (using `pyproject.toml`) changed this integration, potentially affecting older Jupyter notebook workflows that relied on direct file placements for custom extensions.

fix

Review the official documentation for updated Jupyter notebook integration methods if you rely on direct file insertions. For most users using the 'Download as' menu option, this change should be handled by the Jupyter frontend automatically.

affects: >=0.2.5

gotchaBrowser-based image conversion (Chrome, Playwright, Selenium) requires the respective browser (Chromium-based or Firefox) to be installed on the system. Without it, conversion will fail. Browser updates can also introduce compatibility issues (e.g., Chrome v111, v129).

fix

Ensure Google Chrome/Chromium or Firefox (for Selenium) is installed. If issues arise, try updating your browser, updating `dataframe-image`, or switching to an alternative backend like `playwright` or `matplotlib` using the `table_conversion` parameter. For Playwright, run `playwright install` after `pip install "dataframe_image[playwright]"`.

affects: All versions

gotchaThe `matplotlib` backend, while faster and not requiring a browser, has limitations on styling. It can only simulate default header and cell styles (e.g., `background_gradient`, `font-size`) and does not fully support advanced CSS properties or features like `set_caption`.

fix

For full styling fidelity, use a browser-based backend (Playwright, Chrome, Selenium). If `matplotlib` is necessary, be aware of its styling limitations and adjust your DataFrame's presentation accordingly.

affects: All versions

gotchaWhen running `dataframe_image` functions like `dfi.export` or `dfi.convert` within an asynchronous context, such as a Jupyter Notebook cell that is not the primary execution thread, you must use their asynchronous counterparts (e.g., `await dfi.export_async(...)`).

fix

Prepend `await` to your `export` or `convert` calls and ensure the function is defined as `async` if it's not at the top level of a script.

affects: All versions

Errors

Common errors & fixes

No such file or directory: ...\AppData\Local\Temp\tmpXXXXXX\temp.png

The library failed to create or access temporary files/directories needed for image conversion, often due to permission issues, antivirus interference, or insufficient disk space.

fix

Try setting `table_conversion='matplotlib'` or `table_conversion='playwright'` to see if a different backend resolves the temporary file issue. Ensure your user has write permissions to the temporary directory. Restarting your environment or computer might also help clear transient issues.

SyntaxError: not a PNG file

This error typically indicates that the underlying image generation process (usually by a browser backend) failed to produce a valid PNG file, often due to browser compatibility, missing browser, or driver issues.

fix

Verify that your selected browser (Chrome/Chromium for 'chrome'/'html2image', Firefox for 'selenium', or Playwright's browsers) is installed and accessible. Consider upgrading or downgrading your browser or `dataframe-image` package. Switching to `table_conversion='playwright'` (with `pip install "dataframe_image[playwright]"` and `playwright install`) is often a robust solution.

WebDriverException: Message: 'chromedriver' executable needs to be in PATH.

The Chrome browser backend cannot find the necessary `chromedriver` executable, which is required for Selenium/Chrome automation. This can happen if Chrome is not installed or its driver is not in your system's PATH.

fix

Ensure Google Chrome is installed. If it is, `dataframe-image` often auto-detects it. If not, you might need to manually specify the path using the `chrome_path` parameter in `dfi.export()` or `dfi.convert()`, or install a browser using Playwright and use that backend.

LaTeX command `xelatex` not found.

When converting Jupyter Notebooks to PDF using the default LaTeX option, the required LaTeX distribution (e.g., TeX Live or MiKTeX) is not installed on the system or not found in the PATH.

fix

Install a full LaTeX distribution (e.g., TeX Live on Linux/macOS, MiKTeX on Windows). Alternatively, use a browser-based conversion method for PDF output by setting `to='pdf'` and configuring `table_conversion` to a browser backend (e.g., `'playwright'`).

Upgrade

Version history

0.2.7latest on PyPI · released Jan 30, 2025

Audit

Dependencies

pandasrequiredCore functionality for DataFrame manipulation and styling.

nbconvertrequiredRequired for converting Jupyter Notebooks to PDF/Markdown formats.

pillowrequiredImage processing library.

aiohttprequiredAsynchronous HTTP client, often used by browser automation tools.

playwrightoptionalBrowser automation library, the default and recommended backend for image conversion.

seleniumoptionalAlternative browser automation library, used for Firefox backend, particularly useful in Google Colab.

matplotliboptionalAlternative backend for DataFrame image conversion, offers speed and SVG support but with style limitations.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dexplo/dataframe_image ↗

packagehttps://pypi.org/project/dataframe-image/ ↗