Skip to contents

Python setup for DownBallotR

Source: vignettes/articles/python-setup.Rmd
python-setup.Rmd

1. Install the package

You can install the development version from GitHub:

install.packages("pak")
pak::pak("gchickering21/Downballot")

Or using remotes:

install.packages("remotes")
remotes::install_github("gchickering21/Downballot")

Then load the package:

2. First-time setup (required once)

After installing the R package, you must set up the Python environment used by DownBallotR.

Step 1: Install Python via reticulate

DownBallotR manages its own isolated Python environment through reticulate. You do not need to install Python yourself — the following command downloads and installs a standalone Python that reticulate manages independently of anything already on your machine:

reticulate::install_python()

This works on Windows, macOS, and Linux without any prior Python installation. You can pin a specific version if needed (e.g. reticulate::install_python(version = "3.12")); any version 3.10 or later works.

Step 2: Install Python dependencies

Once Python is available, run the following once:

reticulate::virtualenv_starter() automatically selects the best available Python for creating a virtual environment — matching whatever version you just installed. If you installed a specific version in Step 1, pass the same version here (e.g. reticulate::virtualenv_starter("3.12")).

This command:

  • Creates a dedicated Python virtual environment for DownBallotR
  • Installs required Python packages
  • Installs Playwright and its Chromium browser (this may download ~100–200MB the first time)

This step may take a few minutes.

Note: If you already have Python 3.10 or later installed and working on your machine, you can try downballot_install_python() without arguments. If that fails (e.g. with a virtualenv creation error), use the reticulate::install_python() approach above.

Step 2: Verify the setup

After installation completes, check the status:

You should see output indicating:

  • The virtual environment exists
  • Required Python packages are installed
  • Playwright Chromium is available

At this point, Python is installed but not yet active in your R session.

3. Normal usage (each R session)

Each R session must explicitly activate the Python environment once per session.

Activate Python for the session

At the start of any R session where you plan to use DownBallotR, run:

This:

  • Pins reticulate to the correct Python virtual environment
  • Safely initializes Python for the current R session

You only need to run this once per session.

Optional: check status

At any time, you can check the current state of the Python environment:

This reports:

  • Whether Python is initialized
  • Which Python interpreter is active
  • Whether required packages are available

4. Using DownBallotR in future or concurrent sessions

New R session?

If you restart R, open a new RStudio window, or start a separate R process, simply run:

You do not need to reinstall Python.

Multiple R sessions at the same time

If you have multiple R sessions open concurrently:

5. Platform notes

Windows

The setup works on Windows without modification. When installing Python via reticulate::install_python(), ensure you run R with normal user permissions (administrator is not required). Playwright downloads a self-contained Chromium bundle on Windows, so no additional system software is needed.

macOS

The recommended reticulate::install_python() approach works on macOS. If you prefer to use a system Python, any version installed via python.org or Homebrew (brew install python) that is 3.10 or later will work.

Linux

The setup works on Linux, but Playwright’s Chromium browser may require additional system libraries on minimal or server environments. If scraping fails with a browser launch error, run the following in a terminal:

# Debian / Ubuntu
sudo apt-get install -y libglib2.0-0 libnss3 libnspr4 libdbus-1-3 \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 \
  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

# Fedora / RHEL
sudo dnf install -y nss nspr atk at-spi2-atk cups-libs libdrm \
  libxkbcommon libXcomposite libXdamage libXfixes libXrandr mesa-libgbm alsa-lib

Or use Playwright’s built-in dependency installer. Run this once in R after the Python environment is active:

reticulate::py_run_string("from playwright.__main__ import main; import sys; sys.argv = ['playwright', 'install-deps', 'chromium']; main()")

6. Common issues and fixes

Python is not initialized or packages appear missing

Run:

If packages are still missing:

downballot_install_python(reinstall = TRUE)

“reticulate is already initialized to a different Python interpreter”

This occurs when Python is initialized before calling downballot_use_python().

Fix:

  1. Restart your R session
  2. Immediately run:

Then continue using the package.

Reinstall everything from scratch

If the environment becomes corrupted or inconsistent:

First-time setup:

Every new R session:

Check environment status: