News

• 2026-07-27 - Released PCREQ v1.1.0, featuring a rewritten knowledge-base pipeline (direct PyPI download replacing pip install --target), end-to-end determinism (PYTHONHASHSEED elimination), corrected Z3 version solving with user-pin retention and Requires-Python enforcement, and a four-tier call-module detection fallback.

What is PCREQ?

PCREQ is an automated tool for inferring compatible requirements for Python third-party library (TPL) upgrades. It is the first to achieve a fully automated process (end-to-end) that includes knowledge acquisition, version compatibility assessment, invoked APIs and modules extraction, code compatibility assessment, and missing TPL completion. PCREQ specializes in generating a compatible requirements.txt when upgrading a target TPL through a comprehensive analysis of both version and code compatibility issues.

For PCREQ's design and implementation details, please refer to our paper.

Evaluation

REQBench Benchmark for Python Third-Party Libraries Upgrade.

PCREQ's evaluation results are available here.

Usage

Prerequisites

• Linux (tested on Ubuntu 18.04.1)
• Python 3.9.12
• thefuzz 0.22.1
• z3-solver 4.13.4.0
• packaging 24.0
• requests 2.32.3

Step 1: Write the Configuration File

In the configure directory, construct a JSON configuration file, which should include the following information:

{
    "projPath": "/home/usr/project",
    "requirementsPath": "/home/usr/requirements.txt",
    "targetLibrary": "pillow",
    "startVersion": "6.2.0",
    "targetVersion": "7.0.0",
    "pythonVersion": "3.7",
    "knowledgePath": "/home/usr/knowledge/"
}

projPath: project path, requirementsPath: requirements path, targetLibrary: target third-party library name, startVersion: current version of target third-party library, targetVersion: target version of target third-party library, pythonVersion: the Python version, knowledgePath: the path of knowledge.

Given the potentially large knowledge size, knowledgePath supports custom storage locations.

Step 2: Knowledge Acquisition

Option 1: Build KB from Scratch

v1.1.0 builds the knowledge base directly from PyPI by downloading and unpacking wheels/sdists locally without pip install --target, producing a fully reproducible, Linux-only KB.

python knowledge_acquisition.py --config config.json
python batch_knowledge.py --config-dir /path/to/REQBench/configure  # batch build

Option 2: Incremental Update from Pre-built KB

Download the pre-built v1.0.x KB from Zenodo:

• Third-party library source code: libraries-Part1, libraries-Part2, libraries-Part3
• Entities, versions, and constraints: Entities, Versions, Constraints

cd /path/to/knowledge/
mkdir libraries
tar -xzvf *.tar.gz -C libraries      # source code
tar -xzvf *.tar.gz -C .              # entities, versions, constraints

Then point knowledgePath at the extracted KB and run v1.1.0's knowledge_acquisition.py. The legacy-API consistency check detects mismatched API JSONs and triggers selective re-extraction for affected packages — no full rebuild required.

python knowledge_acquisition.py --config config.json
python batch_knowledge.py --config-dir /path/to/REQBench/configure  # batch incremental update

Step 3: Compatible Upgraded requirements.txt Generation

Run Command

python main.py --config config.json

Usage Example

python knowledge_acquisition.py --config config.json
python main.py --config config.json

Output

The output consists of two parts: the updated requirements.txt and an analysis report, which is located in the report directory and contains what PCREQ performed in terms of version and code compatibility checks and fixes. The contents of the report are as follows:

*************Upgrade pillow from 6.2.0 to 7.0.0 in PyTorch-ENet*************
Checking PyTorch-ENet is compatible with pillow7.0.0?...
PyTorch-ENet is compatible with pillow7.0.0
Checking torchvision0.3.0 is compatible with pillow7.0.0?...
torchvision0.3.0 is not compatible with pillow7.0.0-The PIL.PILLOW_VERSION is deprecated.
Checking torchvision0.4.0 is compatible with pillow7.0.0?...
torchvision0.4.0 is not compatible with pillow7.0.0-The PIL.PILLOW_VERSION is deprecated.
Checking PyTorch-ENet is compatible with torchvision0.4.0?...
PyTorch-ENet is compatible with torchvision0.4.0
Checking torchvision0.4.1 is compatible with pillow7.0.0?...
torchvision0.4.1 is not compatible with pillow7.0.0-The PIL.PILLOW_VERSION is deprecated.
Checking PyTorch-ENet is compatible with torchvision0.4.1?...
PyTorch-ENet is compatible with torchvision0.4.1
Checking torchvision0.4.2 is compatible with pillow7.0.0?...
torchvision0.4.2 is not compatible with pillow7.0.0-The PIL.PILLOW_VERSION is deprecated.
Checking PyTorch-ENet is compatible with torchvision0.4.2?...
PyTorch-ENet is compatible with torchvision0.4.2
Checking torchvision0.5.0 is compatible with pillow7.0.0?...
torchvision0.5.0 is compatible with pillow7.0.0
Checking PyTorch-ENet is compatible with torchvision0.5.0?...
PyTorch-ENet is compatible with torchvision0.5.0
Checking torchvision0.5.0 is compatible with torch1.4.0?...
torchvision0.5.0 is compatible with torch1.4.0
Checking PyTorch-ENet is compatible with torch1.4.0?...
PyTorch-ENet is compatible with torch1.4.0
*************New requirements.txt has been generated!*************
Time cost: 9.06177806854248 s

Citation

If PCREQ supports your research or development work, please cite the following publication.

@article{PCREQ_TOSEM2026,
  author={Lei, Huashan and Xiao, Guanping and Liu, Yepang and Zheng, Zheng},
  journal={ACM Transactions on Software Engineering and Methodology},
  title={PCREQ: Automated Inference of Compatible Requirements for Python Third-party Library Upgrades},
  year={2026},
  doi={10.1145/3806394}
}

License

PCREQ is licensed under the GNU Affero General Public License v3.0. See LICENSE.txt for details.