pypaperretriever 1.0.1

A tool to retrieve and process academic papers

PyPaperRetriever

👉 Full Documentation
👉 Start with the Quickstart

A python package for retrieving scientific papers from the web. Inspired by PyPaperBot (https://github.com/ferru97/PyPaperBot) but with improved flexibility and extensibility. Prefers open-access sources but users can opt to use Sci-Hub as a fallback depending on their ethical considerations and local laws.

Installation

pip install pypaperretriever

Or install the latest development version directly from GitHub:

pip install git+https://github.com/josephisaacturner/pypaperretriever.git

Features

• Download papers using DOI or PubMed ID (PMID)
• Search PubMed programmatically with advanced query options
• Track citation networks (both upstream and downstream) for papers of interest
• Extract images from downloaded PDFs
• Find all available sources from Unpaywall and optional Sci-Hub integration
• Keep track of sources used via JSON sidecar files for each download
• Avoid duplicate downloads with intelligent checking
• BIDS-compatible file naming convention
• Both command-line and Python API interfaces
• Advanced search capabilities with customizable filters
• Citation network analysis tools

Ethical and legal note on Sci-Hub

Use of Sci-Hub is disabled by default and clearly labeled. Institutions and researchers differ in policy and legal context; PyPaperRetriever exposes an opt-in flag so users can comply with local rules while retaining a complete pipeline for contexts where such access is permitted. The authors of PyPaperRetriever do not endorse or encourage the use of Sci-Hub in violation of local laws or institutional policies. Users are responsible for ensuring compliance with all applicable laws and ethical guidelines when using this tool.

Usage Examples

For complete examples, see examples.ipynb in the repository.

1. Download Using DOI

from pypaperretriever import PaperRetriever

retriever = PaperRetriever(
    email="[e-mail]",
    doi="10.7759/cureus.76081",
    download_directory='PDFs'
)
retriever.download()

# Command-line alternative
pypaperretriever --doi 10.7759/cureus.76081 --email [e-mail] --dwn-dir PDFs

2. Download Using PubMed ID

from pypaperretriever import PaperRetriever

retriever = PaperRetriever(
    email="[e-mail]",
    pmid="33813262",
    download_directory='PDFs'
)
retriever.download()

# Command-line alternative
pypaperretriever --pmid 33813262 --email [e-mail] --dwn-dir PDFs

3. Control Sci-Hub Access

retriever = PaperRetriever(
    email="[e-mail]",
    doi="10.1016/j.revmed.2011.10.009",
    download_directory='PDFs',
    allow_scihub=False  # Set to True to enable Sci-Hub
)
retriever.download()

4. Extract Images from PDFs

from pypaperretriever import ImageExtractor

extractor = ImageExtractor('path/to/your/paper.pdf')
extractor.extract_images()

5. Search PubMed Programmatically

from pypaperretriever import PubMedSearcher

search_query = """("brain lesions"[MeSH Terms] OR "brain lesion"[Title/Abstract] OR 
                   "cerebral lesion"[Title/Abstract]) AND (case reports[Publication Type])"""

searcher = PubMedSearcher(search_string=search_query, email="[e-mail]")

results = searcher.search(
    count=10,
    order_by='relevance',  # or 'chronological'
    only_open_access=False,
    only_case_reports=False
)

# Download found articles
searcher.download_articles(download_directory='PDFs', allow_scihub=True)

# Extract images from downloaded articles
searcher.extract_images()

6. Track Citation Networks

from pypaperretriever import PaperTracker

tracker = PaperTracker(
    email="[e-mail]",
    doi='10.1097/RLU.0000000000001894',
    max_upstream_generations=1,   # Papers referenced by your paper
    max_downstream_generations=1  # Papers that cite your paper
)

results = tracker.track_paper()

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Citation

If you use PyPaperRetriever in your research, please cite:

Turner et al., (2025). PyPaperRetriever: A Python Tool for Finding and Downloading Scientific Literature. Journal of Open Source Software, 10(113), 8135, https://doi.org/10.21105/joss.08135