# Migrate From PyPDF2 to pypdf and Fix "PdfFileReader is deprecated and was removed"

Yes. An agent renames the removed PyPDF2 classes and methods, switches the dependency to pypdf, compares the PDFs old and new code write, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-pypdf2-to-pypdf/pypdf2/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The error arrives without a code change. A script that worked for years is installed on a new machine, `pip` resolves an unpinned `PyPDF2` to 3.0.1, and the first line that touches a PDF raises `PyPDF2.errors.DeprecationError: PdfFileReader is deprecated and was removed in PyPDF2 3.0.0. Use PdfReader instead.` The agent reads how the dependency is declared before it reads the code. In a tool like yourcelf/signpdf, which stamps a signature image onto one page of a PDF, `requirements.txt` lists `pypdf2` and `reportlab` with no versions and `setup.py` repeats both in `install_requires`, so every fresh install gets the release that removed the old names.

PyPDF2 3.0.1, published at the end of 2022, is the last release under that name; the project continued as `pypdf`. Renaming to the 3.x API alone would stop the error and leave the script on a package that receives no fixes, so the agent moves to `pypdf` in the same change. `signpdf.py` uses eight old names: `PdfFileReader`, `PdfFileWriter`, `getNumPages`, `getPage`, `cropBox`, `mediaBox`, `mergePage` and `addPage`. They become `PdfReader`, `PdfWriter`, `len(reader.pages)`, `reader.pages[i]`, `cropbox`, `mediabox`, `merge_page` and `add_page`. The agent does not take that mapping from memory. It installs PyPDF2 2.12.1, the last line that still runs the old names, and runs the script with warnings enabled: each deprecated call prints its own replacement, and those messages are the list it works from.

The repository has no tests, so the agent builds the evidence. It generates a three-page PDF and a small PNG, then runs the unchanged script under PyPDF2 1.26.0 and the ported script under `pypdf`, with the same `--coords` argument. It opens both outputs and compares them page by page: the page count, the text extracted from each page, the media box, and the presence of exactly one image form on the signed page and none on the others. On signpdf those match. It does not compare bytes, because the two libraries write objects in a different order and the files differ in size by a few bytes without differing in content.

Then it writes that comparison down as a test, with pytest and the two generated fixtures, so the next library upgrade has something to run. It updates `requirements.txt` and `install_requires` to `pypdf`, and adds `python_requires` to match the Python versions the chosen `pypdf` release supports, since `setup.py` declares none. It leaves alone what it noticed and was not asked to change, such as the helper that returns a temporary file's name after the file has been closed, and mentions it in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "This project fails with 'PdfFileReader is deprecated and was removed in PyPDF2 3.0.0'. Migrate it from PyPDF2 to pypdf. Read every file that declares dependencies (requirements files, setup.py, setup.cfg, pyproject.toml, lock files) and report how PyPDF2 is specified and which version a fresh install resolves to today. List every PyPDF2 name the code uses: classes, methods, properties and exception classes. To get the replacement for each, install the last PyPDF2 2.x release in a scratch environment, run the code with warnings shown, and use the deprecation messages; quote them. Port the code to pypdf, changing imports, class names, method names and property names, and nothing else. If the project has tests, run them before and after. If it has none, generate small input files, run the old code under an old PyPDF2 release that still works and the new code under pypdf, and compare the outputs by content: page count, extracted text per page, page boxes, and whatever the code adds or removes. Do not compare raw bytes. Save both output files as artifacts of this run so a reviewer can open them. Turn that comparison into a pytest test and commit it with its fixtures. Replace PyPDF2 with pypdf in every dependency file, keep the project's pinning style, and set the minimum Python version to what the pypdf release requires if the project declares none or a lower one. List anything else you noticed but did not change. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes the import and ten other lines in `signpdf.py`, the dependency name in `requirements.txt` and `setup.py`, and adds a test file with two small fixtures. The description begins with the original traceback and the version a fresh install resolved to, then a table of old name, new name and the deprecation message that justified each. Below that is the output comparison: one row per page with the values from the old and the new run.

A reviewer looks first for names that were renamed by guess. A property such as `cropBox` fails only when its line runs, so a call the comparison never reached is unproven, and the description says which lines the generated inputs exercised. They check that both dependency files changed, because `pip install signpdf` reads `setup.py` and not `requirements.txt`. They can open the two output PDFs, which come back as artifacts on the session, and look at the signature placement themselves.

## Run it on every script you find while working in your editor

PyPDF2 imports hide in one-file tools across many repositories, and you tend to meet them one at a time while doing something else. Rush's API is also an MCP server at `https://api.phoenix.so/mcp`. Add it to your MCP client with an API key and the agent in your editor can hand the job over the moment it sees the import: it calls `create_session` with this prompt and the repository, gets the session back at once, and goes on with what you asked it for.

When you want the result, the same client calls `wait_for_sessions`, which waits up to 50 seconds per call for a session to settle, and `get_session` returns the answer and the pull request. A run started this way with an API key is a developer run: it uses Rush's models, billed per token to the member who created the key.

## Why run it on Rush?

Three versions of one library have to be installed side by side to do this properly: the old release that still runs the code, the last 2.x release for its deprecation messages, and `pypdf`. The run creates those environments in its own sandbox and nothing on your machine changes. Every command and its output is kept in the session transcript, including the warnings the name mapping came from.

The comparison of output files is the proof, and it is the step people skip. Renaming methods until the traceback goes away shows only that the script no longer crashes on the path you tried. Generating inputs, producing a PDF with both libraries and checking them page by page shows the tool still does its job, and the resulting test stays in the repository.

## Frequently asked questions

### Can I just pin PyPDF2 below 3.0 instead?

It stops the error and is a reasonable stopgap for one deploy. PyPDF2 2.x still runs the old names and prints a warning for each. But no PyPDF2 release has been published since 3.0.1, so a pin keeps you on code that gets no bug or security fixes. The port is mostly renames, and doing it once ends the problem.

### Is pypdf a drop-in replacement for PyPDF2 3.x?

For code already using the 3.x names, changing `import PyPDF2` to `import pypdf` covers most of it, since `pypdf` continued from that codebase. Later `pypdf` releases removed more deprecated names and raised the minimum Python version, so run your tests after switching. Code still on `PdfFileReader` needs the renames first.

### What replaces getPage, getNumPages and addPage?

`reader.pages[i]` replaces `reader.getPage(i)`, `len(reader.pages)` replaces `reader.getNumPages()` and `writer.add_page(page)` replaces `writer.addPage(page)`. Page properties moved to lower case, for example `mediaBox` to `mediabox`, and `mergePage` became `merge_page`. `extractText` became `extract_text`.

### Will the output PDF be byte-identical?

No, and it does not need to be. Different library versions number and order the objects in the file differently, so sizes and hashes change. What should match is the content: the same pages, text, boxes and added elements. That is what the agent's comparison checks.

### What about PyPDF3 or PyPDF4?

Those are separate forks made while PyPDF2 was inactive. The maintained line today is `pypdf`, which is where the PyPDF2 project itself moved. If a project imports `PyPDF3` or `PyPDF4`, the agent treats it the same way: find the names in use, map them, and compare outputs.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From python-jose to PyJWT in a FastAPI App](https://getrush.ai/run/migrate-python-jose-to-pyjwt/python-jose/)
- [Migrate From raven to sentry-sdk in a Django App](https://getrush.ai/run/migrate-raven-to-sentry-sdk/raven/)
- [Migrate From React Query v3 to TanStack Query v5](https://getrush.ai/run/migrate-react-query-to-tanstack-query/react-query/)
- [Migrate a React App From Redux to Redux Toolkit](https://getrush.ai/run/migrate-redux-to-redux-toolkit/redux/)
- [Replace the Deprecated request Package With Native fetch](https://getrush.ai/run/migrate-request-to-fetch/request/)
- [Replace rimraf and mkdirp With fs.rm and fs.mkdir in a Node.js Package](https://getrush.ai/run/migrate-rimraf-to-fs-rm/rimraf/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
