Tutorial

Here we will show the basic commands for working with pygscholar. When you install pygscholar you will get access to the scholar command which you can use in the terminal. In this tutorial we are running the commands from a notebook and therefore all commands starts with a !. However if you are using a terminal, then you should not use the ! in front of the command.

The help option

To see all the available options, you can type

$ scholar --help

!scholar --help

                                                                                
 Usage: scholar [OPTIONS] COMMAND [ARGS]...                                     
                                                                                
 Command line interface for pygscholar. You can also set the environment        
 variable `PYSCHOLAR_CACHE_DIR` to change the default cache directory.          
                                                                                

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version                     Show version                                   │
│ --license                     Show license                                   │
│ --install-completion          Install completion for the current shell.      │
│ --show-completion             Show completion for the current shell, to copy │
│                               it or customize the installation.              │
│ --help                        Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list-authors                      List all authors                           │
│ search-author                     Search for authors                         │
│ add-author                        Add new author                             │
│ remove-author                     Remove author                              │
│ list-author-publications          List authors publications                  │
│ list-new-author-publications      List new authors publications              │
│ list-department-publications      List department publications               │
│ list-new-department-publications  List department publications               │
│ generate-test-data                Generate test data                         │
│ download-test-data                Download test data                         │
╰──────────────────────────────────────────────────────────────────────────────╯

This will list all the available options with a message explaining the different sub-commands. For each sub-command you can also use the --help option, e.g

$ scholar add-author --help

!scholar add-author --help

                                                                                
 Usage: scholar add-author [OPTIONS] NAME                                       
                                                                                
 Add new author                                                                 
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name      TEXT  [required]                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --scholar-id        TEXT                                                     │
│ --cache-dir         TEXT                 [default: /home/runner/.pygscholar] │
│ --backend           [scraper|scholarly]  [default: scraper]                  │
│ --help                                   Show this message and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯

First we will download some test data in order not to spam Google Scholar with requests. This is only needed because Google scholar rejects requests if they are coming from an automated service. This is not needed if you run this from the terminal.

!scholar download-test-data local_db.json

Downloading test data from https://drive.usercontent.google.com/download?id=1bX2TL41jcseXvfrMOmwAjBsW9BJ8J5bB&confirm=xxx to local_db.json

Adding an author to your database

The way pygscholar works is that you need to add authors to a database in order for pygscholar to find them. First we can try to list all the authors in our database using the command

$ scholar list-authors

!scholar list-authors

2026-04-28 05:44:11 [info     ] Cache dir /home/runner/.pygscholar does not exist. Creating...
       Authors       
┏━━━━━━┳━━━━━━━━━━━━┓
┃ Name ┃ Scholar ID ┃
┡━━━━━━╇━━━━━━━━━━━━┩
└──────┴────────────┘

Now we could try to add an author to the database by using the command

$ scholar add-author <name of author>

e.g

$ scholar add-author 'Henrik Finsberg'

!scholar add-author 'Henrik Finsberg'

2026-04-28 05:44:12 [info     ] Searching for author Henrik Finsberg
2026-04-28 05:44:12 [debug    ] Found 1 author(s)             
Adding author Henrik Nicolay Finsberg
Successfully added author with name Henrik Nicolay Finsberg and scholar id NDPIHoEAAAAJ
Search for publications. This can take some time

2026-04-28 05:44:12 [info     ] Get author info for Henrik Nicolay Finsberg
2026-04-28 05:44:12 [info     ] Searching for author Henrik Nicolay Finsberg
2026-04-28 05:44:12 [debug    ] Found 1 author(s)             
2026-04-28 05:44:12 [debug    ] Extracting all articles for NDPIHoEAAAAJ
2026-04-28 05:44:12 [info     ] Updating author info for Henrik Nicolay Finsberg
2026-04-28 05:44:12 [debug    ] Extracting author info        
2026-04-28 05:44:12 [debug    ] Extracting co-authors         

You can now try to list the authors again

!scholar list-authors

Henrik Nicolay Finsberg
                 Authors                  
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃                    Name ┃ Scholar ID   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Henrik Nicolay Finsberg │ NDPIHoEAAAAJ │
└─────────────────────────┴──────────────┘

As we can see, we didn’t type the full name (i.e Henrik Nicolay Finsberg), but the program was still able to find the correct author. Sometimes there are more than one person with the same name, in which case you can use the Scholar ID to specify which person you mean. We can first use the command

$ scholar search-author

to search for an author. This would be equivalent of searching for an author at Google Scholar. Let us say that we want to add a person with surname ‘Dokken’ that we know work at Simula Research Laboratory. We can then search for Dokken

$ scholar search-author 'Dokken'

!scholar search-author 'Dokken'

2026-04-28 05:44:14 [info     ] Searching for author Dokken   

2026-04-28 05:44:14 [debug    ] Found 3 author(s)             
                Search results for author 'Dokken'                
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Name                   ┃ Scholar ID   ┃ Affiliation ┃ Cited by ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Trond Dokken           │ 42hVWYwAAAAJ │             │ 0        │
│ Tor Dokken             │ vkPMFtwAAAAJ │             │ 0        │
│ Jørgen Schartum Dokken │ hfeXoYMAAAAJ │             │ 0        │
└────────────────────────┴──────────────┴─────────────┴──────────┘

We see that, the person we are looking for is Jørgen Dokken, so we could go ahead an add this author, or we could use the Scholar ID as follows

$ scholar add-author 'Dokken' --scholar-id=hfeXoYMAAAAJ

!scholar add-author 'Dokken' --scholar-id=hfeXoYMAAAAJ

2026-04-28 05:44:14 [info     ] Searching for author Dokken   

2026-04-28 05:44:14 [debug    ] Found 3 author(s)             
Adding author Jørgen Schartum Dokken
Successfully added author with name Jørgen Schartum Dokken and scholar id hfeXoYMAAAAJ
Search for publications. This can take some time
2026-04-28 05:44:14 [info     ] Get author info for Jørgen Schartum Dokken
2026-04-28 05:44:14 [info     ] Searching for author Jørgen Schartum Dokken
2026-04-28 05:44:14 [debug    ] Found 1 author(s)             
2026-04-28 05:44:14 [debug    ] Extracting all articles for hfeXoYMAAAAJ
2026-04-28 05:44:14 [info     ] Updating author info for Jørgen Schartum Dokken
2026-04-28 05:44:14 [debug    ] Extracting author info        
2026-04-28 05:44:14 [debug    ] Extracting co-authors         

We can now list the authors again

!scholar list-authors

Henrik Nicolay Finsberg
Jørgen Schartum Dokken
                 Authors                  
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃                    Name ┃ Scholar ID   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Henrik Nicolay Finsberg │ NDPIHoEAAAAJ │
│  Jørgen Schartum Dokken │ hfeXoYMAAAAJ │
└─────────────────────────┴──────────────┘

Listing author publications

The next command we want to look at is the command

$ scholar list-author-publications

We can take a look at the help section first

!scholar list-author-publications --help

                                                                                
 Usage: scholar list-author-publications [OPTIONS] NAME                         
                                                                                
 List authors publications                                                      
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name      TEXT  [required]                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --n                                      INTEGER           [default: 5]      │
│ --sort-by-citati…    --no-sort-by-ci…                      [default:         │
│                                                            sort-by-citation… │
│ --add-authors        --no-add-authors                      [default:         │
│                                                            no-add-authors]   │
│ --max-age                                INTEGER                             │
│ --update             --no-update                           [default:         │
│                                                            no-update]        │
│ --overwrite          --no-overwrite                        [default:         │
│                                                            no-overwrite]     │
│ --cache-dir                              TEXT              [default:         │
│                                                            /home/runner/.py… │
│ --backend                                [scraper|scholar  [default:         │
│                                          ly]               scraper]          │
│ --help                                                     Show this message │
│                                                            and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯

We see that the command takes a name, which is the name of the author. Let us try it on one of the names in the database

!scholar list-author-publications 'Henrik Finsberg'

Could not find author with name 'Henrik Finsberg'. Will use 'Henrik Nicolay Finsberg' instead
         Publications for Henrik Nicolay Finsberg (Sorted by citations)         
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Title                                 ┃ Published year ┃ Number of citations ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ Efficient estimation of personalized  │ 2018           │ 61                  │
│ biventricular mechanical function     │                │                     │
│ employing gradient‐based optimization │                │                     │
│ Improved computational identification │ 2020           │ 54                  │
│ of drug response using optical        │                │                     │
│ measurements of human stem cell       │                │                     │
│ derived cardiomyocytes in             │                │                     │
│ microphysiological systems            │                │                     │
│ Estimating cardiac contraction        │ 2018           │ 40                  │
│ through high resolution data          │                │                     │
│ assimilation of a personalized        │                │                     │
│ mechanical model                      │                │                     │
│ Computational quantification of       │ 2019           │ 35                  │
│ patient-specific changes in           │                │                     │
│ ventricular dynamics associated with  │                │                     │
│ pulmonary hypertension                │                │                     │
│ In vivo estimation of elastic         │ 2018           │ 29                  │
│ heterogeneity in an infarcted human   │                │                     │
│ heart                                 │                │                     │
└───────────────────────────────────────┴────────────────┴─────────────────────┘

We see that it will display the 5 most cited papers, sorted with the most cited paper on top. We can also choose to display only 3 papers (using the --n flag), and we can also choose to not display papers that are more than two years old (using the --max-age flag). Let us also add all the authors on the papers for each row using the --add-authors flag

!scholar list-author-publications 'Henrik Finsberg' --n=3 --max-age=2 --add-authors

Could not find author with name 'Henrik Finsberg'. Will use 'Henrik Nicolay Finsberg' instead
         Publications for Henrik Nicolay Finsberg (Sorted by citations)         
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃                    ┃                   ┃                ┃ Number of          ┃
┃ Title              ┃ Authors           ┃ Published year ┃ citations          ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ A software         │ R Aróstica, D     │ 2025           │ 15                 │
│ benchmark for      │ Nolte, A Brown, A │                │                    │
│ cardiac            │ Gebauer, E        │                │                    │
│ elastodynamics     │ Karabelas, J      │                │                    │
│                    │ Jilberto, ...     │                │                    │
│ Spatial modeling   │ EA Francis, JG    │ 2025           │ 13                 │
│ algorithms for     │ Laughlin, JS      │                │                    │
│ reactions and      │ Dokken, HNT       │                │                    │
│ transport in       │ Finsberg, CT Lee, │                │                    │
│ biological cells   │ ME Rognes, ...    │                │                    │
│ A computational    │ OO Odeigah, ED    │ 2024           │ 7                  │
│ study of right     │ Kwan, KM Garcia,  │                │                    │
│ ventricular        │ H Finsberg, D     │                │                    │
│ mechanics in a rat │ Valdez-Jasso, ... │                │                    │
│ model of pulmonary │                   │                │                    │
│ arterial           │                   │                │                    │
│ hypertension       │                   │                │                    │
└────────────────────┴───────────────────┴────────────────┴────────────────────┘

Listing publications for the whole department

Our department now consists of two researchers (Henrik Finsberg and Jørgen Dokken), but you could imaging that you have a lot of researchers in your department. It would then be nice to list the most cited papers across the whole department. We can do this with the

$ scholar list-department-publications

command. Let us first loook at the help menu

!scholar list-department-publications --help

                                                                                
 Usage: scholar list-department-publications [OPTIONS]                          
                                                                                
 List department publications                                                   
                                                                                

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --n                                      INTEGER           [default: 5]      │
│ --sort-by-citati…    --no-sort-by-ci…                      [default:         │
│                                                            sort-by-citation… │
│ --add-authors        --no-add-authors                      [default:         │
│                                                            no-add-authors]   │
│ --max-age                                INTEGER                             │
│ --update             --no-update                           [default:         │
│                                                            no-update]        │
│ --cache-dir                              TEXT              [default:         │
│                                                            /home/runner/.py… │
│ --backend                                [scraper|scholar  [default:         │
│                                          ly]               scraper]          │
│ --help                                                     Show this message │
│                                                            and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯

Let us list the most cited papers not older than 2 year using the command

$ scholar list-department-publications --max-age=2

!scholar list-department-publications --max-age=2

               Publications for department (Sorted by citations)                
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Title                                 ┃ Published year ┃ Number of citations ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ A software benchmark for cardiac      │ 2025           │ 15                  │
│ elastodynamics                        │                │                     │
│ Spatial modeling algorithms for       │ 2025           │ 13                  │
│ reactions and transport in biological │                │                     │
│ cells                                 │                │                     │
│ DefElement: an encyclopedia of finite │ 2025           │ 11                  │
│ element definitions                   │                │                     │
│ A computational study of right        │ 2024           │ 7                   │
│ ventricular mechanics in a rat model  │                │                     │
│ of pulmonary arterial hypertension    │                │                     │
│ Human induced pluripotent stem        │ 2025           │ 6                   │
│ cell-derived cardiomyocytes and their │                │                     │
│ use in a cardiac organ-on-a-chip to   │                │                     │
│ assay electrophysiology, calcium and  │                │                     │
│ contractility                         │                │                     │
└───────────────────────────────────────┴────────────────┴─────────────────────┘

We can also get the 5 most recent publications using the --no-sort-by-citations flag

!scholar list-department-publications --no-sort-by-citations

                  Publications for department (Sorted by age)                   
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Title                                 ┃ Published year ┃ Number of citations ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ Mathematical Modelling of the Human   │ 2026           │ 2                   │
│ Brain II: From Glymphatics to Deep    │                │                     │
│ Learning                              │                │                     │
│ The FEniCS Project: The FEniCS 2024   │ 2026           │ 0                   │
│ Conference                            │                │                     │
│ Growth and Remodelling Package in     │ 2026           │ 0                   │
│ FEniCSx                               │                │                     │
│ Statistical Atlas-Based Surrogate     │ 2026           │ 0                   │
│ Model of Biventricular Wall Mechanics │                │                     │
│ Cardiac 3D electromechanical tissue   │ 2025           │ 0                   │
│ simulations for cardiac safety        │                │                     │
│ analysis                              │                │                     │
└───────────────────────────────────────┴────────────────┴─────────────────────┘

It is also to possible to list new publications using the command

!scholar list-new-department-publications

2026-04-28 05:44:20 [info     ] Get author info for Henrik Nicolay Finsberg
2026-04-28 05:44:20 [info     ] Searching for author Henrik Nicolay Finsberg
2026-04-28 05:44:20 [debug    ] Found 1 author(s)             
2026-04-28 05:44:20 [debug    ] Extracting all articles for NDPIHoEAAAAJ
2026-04-28 05:44:20 [info     ] Updating author info for Henrik Nicolay Finsberg
2026-04-28 05:44:20 [debug    ] Extracting author info        
2026-04-28 05:44:20 [debug    ] Extracting co-authors         
2026-04-28 05:44:20 [info     ] Get author info for Jørgen Schartum Dokken
2026-04-28 05:44:20 [info     ] Searching for author Jørgen Schartum Dokken
2026-04-28 05:44:20 [debug    ] Found 1 author(s)             
2026-04-28 05:44:20 [debug    ] Extracting all articles for hfeXoYMAAAAJ
2026-04-28 05:44:20 [info     ] Updating author info for Jørgen Schartum Dokken
2026-04-28 05:44:20 [debug    ] Extracting author info        
2026-04-28 05:44:20 [debug    ] Extracting co-authors         
     Publications for department (Sorted by     
                   citations)                   
┏━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Title ┃ Published year ┃ Number of citations ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
└───────┴────────────────┴─────────────────────┘