👉 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.
pip install git+https://github.com/josephisaacturner/pypaperretriever.git- 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
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.
For complete examples, see examples.ipynb in the repository.
from pypaperretriever import PaperRetriever
retriever = PaperRetriever(
email="your.email@gmail.com",
doi="10.7759/cureus.76081",
download_directory='PDFs'
)
retriever.download()
# Command-line alternative
pypaperretriever --doi 10.7759/cureus.76081 --email your.email@gmail.com --dwn-dir PDFsfrom pypaperretriever import PaperRetriever
retriever = PaperRetriever(
email="your.email@gmail.com",
pmid="33813262",
download_directory='PDFs'
)
retriever.download()
# Command-line alternative
pypaperretriever --pmid 33813262 --email your.email@gmail.com --dwn-dir PDFsretriever = PaperRetriever(
email="your.email@gmail.com",
doi="10.1016/j.revmed.2011.10.009",
download_directory='PDFs',
allow_scihub=False # Set to True to enable Sci-Hub
)
retriever.download()from pypaperretriever import ImageExtractor
extractor = ImageExtractor('path/to/your/paper.pdf')
extractor.extract_images()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="your.email@gmail.com")
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()from pypaperretriever import PaperTracker
tracker = PaperTracker(
email="your.email@gmail.com",
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()Contributions are welcome! Please feel free to submit a Pull Request.
MIT License
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