ppget
A simple CLI tool to easily download PubMed articles
ppget is a command-line tool for searching and downloading literature data from PubMed. It focuses on being easy to run immediately: no multi-step pipelines, just one command that delivers CSV/JSON plus metadata.
✨ Features
- 🚀 No installation required - Run instantly with
uvx - 📝 CSV/JSON support - Easy to use in spreadsheets or programs
- 🔍 Flexible search - Full support for PubMed search syntax (AND, OR, MeSH, etc.)
- 📊 Automatic metadata - Automatically records search queries and timestamps
- 🎯 Simple API - Clear and intuitive options
🚀 Quick Start
Run without installation (Recommended)
If you have uv installed, you can run it instantly without installation:
# Basic usage
uvx ppget "machine learning AND medicine"
# Specify number of results
uvx ppget "COVID-19 vaccine" -l 50
# Save as JSON
uvx ppget "cancer immunotherapy" -f json
Install and use
For frequent use, you can install it:
# Install with pip
pip install ppget
# Install with uv
uv tool install ppget
# Run
ppget "your search query"
📖 Usage
Basic usage
# Simple search (CSV format by default, up to 100 results)
ppget "diabetes treatment"
# Example output:
# Searching PubMed...
# Query: 'diabetes treatment'
# Max results: 100
# ✓ Found 100 articles
# ✓ Saved 100 articles to pubmed_20251018_143022.csv
# ✓ Metadata saved to pubmed_20251018_143022.meta.txt
Options
ppget [query] [options]
Required:
query Search query (wrap in quotes only when the query contains spaces or shell-special characters)
Options:
-l, --limit Maximum number of results (default: 100)
-o, --output Output file or directory
-f, --format Output format: csv or json (default: csv)
-e, --email Email address (for API rate limit relaxation)
-q, --quiet Suppress progress messages (errors only)
-v, --version Show version and exit
-h, --help Show help message
Advanced usage
1. Change number of results
# Retrieve up to 200 results
ppget "machine learning healthcare" -l 200
2. Specify output format
# Save as JSON
ppget "spine surgery" -f json
# Default is CSV (can be opened in Excel)
ppget "orthopedics" -f csv
3. Specify filename
# Specify file path directly
ppget "cancer research" -o results/cancer_papers.csv
# Specify directory (filename is auto-generated)
ppget "neuroscience" -o ./data/
# Extension determines format
ppget "cardiology" -o heart_disease.json
4. Specify email address (recommended for heavy usage)
NCBI requests a contact email for tools that access the E-utilities API. Providing one helps them reach you about issues and may reduce rate-limiting for larger batches:
ppget "genomics" -e your.email@example.com -l 500
5. Use PubMed search syntax
# AND search
ppget "machine learning AND radiology"
# OR search
ppget "COVID-19 OR SARS-CoV-2"
# MeSH term search
ppget "Diabetes Mellitus[MeSH] AND Drug Therapy[MeSH]"
# Filter by year
ppget "cancer immunotherapy AND 2024[PDAT]"
# Search by author
ppget "Smith J[Author]"
# Complex search
ppget "(machine learning OR deep learning) AND (radiology OR imaging) AND 2023:2024[PDAT]"
📁 Output Format
CSV format (default)
Easy to open in spreadsheets. A metadata file (.meta.txt) is also generated.
pubmed_20251018_143022.csv # Article data
pubmed_20251018_143022.meta.txt # Search metadata
CSV columns:
pubmed_id- PubMed IDpubmed_link- Direct link to the PubMed article pagetitle- Titleabstract- Abstractjournal- Journal namepublication_date- Publication datedoi- DOIauthors- Author list (semicolon-separated)keywords- Keywords (semicolon-separated)
JSON format
Easy to process programmatically.
[
{
"pubmed_id": "12345678",
"title": "...",
"abstract": "...",
...
}
]
Metadata file (.meta.txt):
Query: machine learning
Search Date: 2025-10-18 14:30:22
Retrieved Results: 100
Data File: pubmed_20251018_143022.json
ℹ️ Tips
- Quotes around the query are optional when it is a single token (e.g.
ppget diabetes). Use quotes when the query contains spaces, parentheses, logical operators, or shell-special characters. - Add
-e your.email@example.comif you plan to run many requests or large limits. It identifies your tool to NCBI and can keep you within their published rate limits (default 3 req/sec without email, up to 10 req/sec with email & api key).
💡 Use Cases
Collecting research papers
# Collect latest papers on a specific topic
ppget "CRISPR gene editing" -l 100 -o crispr_papers.csv
# Run multiple searches at once
ppget "diabetes treatment 2024[PDAT]" -o diabetes_2024.csv
ppget "cancer immunotherapy 2024[PDAT]" -o cancer_2024.csv
For data analysis
# Retrieve in JSON format and analyze with Python
ppget "artificial intelligence healthcare" -f json -l 500 -o ai_health.json
# Example Python code to read
import json
with open('ai_health.json') as f:
data = json.load(f)
# Analysis...
Literature review
# Retrieve in CSV and manage in Excel
ppget "systematic review AND meta-analysis" -l 200 -o reviews.csv
# → Open in Excel and review titles and abstracts
🤝 Contributing
Bug reports and feature requests are welcome at Issues.
📄 License
MIT License - See LICENSE for details.
🙏 Acknowledgments
This tool uses pymed-paperscraper.
Start searching PubMed easily and quickly!
uvx ppget "your research topic"
Metadata
Release files for ppget 0.1.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ppget-0.1.10.tar.gz | 31.6 kB | Without provenance | Details for ppget-0.1.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ppget-0.1.10-py3-none-any.whl | Python 3 | none | any | Details for ppget-0.1.10-py3-none-any.whl |
Total release size: 43.7 kB
Release files / ppget-0.1.10.tar.gz
| Download URL | ppget-0.1.10.tar.gz |
|---|---|
| Size | 31.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9fe9bd7e2585ce338bd0f81aada9ce8e2e9ea1d6b5209da1ba65ce6ae1f60712
|
|
BLAKE2b-256 checksum How to use checksums |
56223dad7a1cc93314973e95e8fbc57d3c3865900110fe8fe5d16734088fc239
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / ppget-0.1.10-py3-none-any.whl
| Download URL | ppget-0.1.10-py3-none-any.whl |
|---|---|
| Size | 12.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9fc0aae0c5821d122fa5c93392a16f3544111744e83298c4c4e515f354576656
|
|
BLAKE2b-256 checksum How to use checksums |
a0e6bec6340462c9e2c5480dbca21b73dffabeee54805f1006e09a675e0bc1ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for ppget 0.1.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.