dataframe-image

Common errors

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

  cause 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

  cause 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.

  cause 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.

  cause 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'`).

Warnings

• breaking The 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.
• breaking Version 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.
• gotcha Browser-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]"`.
• gotcha The `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.
• gotcha When 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.

Install

• pip install dataframe-image Core installation
• pip install "dataframe_image[playwright]" Install with Playwright backend (recommended)

Imports

• dataframe_image

  import dataframe_image as dfi

• export
  wrong:

  dataframe_image.export(...)

  correct:

  dfi.export(...)

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

Quickstart

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")