Pyalex

0.21 verified Mon Apr 27 auth: no python

Pyalex is a Python wrapper for the OpenAlex API, providing convenient access to scholarly data (authors, works, institutions, etc.) from the OpenAlex database. Current version is 0.21, requiring Python >=3.8. It follows the OpenAlex API versioning and is actively maintained.

pip install pyalex

Common errors

error ModuleNotFoundError: No module named 'pyalex.Works' ↓

cause Incorrect import path; Works is a class, not a submodule.

fix

Use from pyalex import Works instead of from pyalex.Works import Works.

error TypeError: 'Config' object is not callable ↓

cause Trying to call Config() as a function; Config is a class used to set attributes directly.

fix

Do not instantiate Config. Use Config.email = '...' directly.

error AttributeError: 'Works' object has no attribute '__iter__' ↓

cause In pyalex 0.20+, Works() is no longer iterable without calling .get(). This is a common error when upgrading from older versions.

fix

Call .get() on the query object before iterating, e.g., for work in Works().get():.

Warnings

breaking In pyalex 0.19 and earlier, the `Works()` call without arguments returned an iterator over all works. In 0.20+, you must explicitly call `.get()` to execute the query. Direct iteration over `Works()` without `.get()` now raises a TypeError. ↓

fix Add `.get()` to the end of your query chain, e.g., `Works().search('AI').get()`.

gotcha The OpenAlex API has a rate limit of 10 requests per second for unauthenticated requests and 100 per second with an email header. Pyalex does not automatically add email; you must set `Config.email`. Without it, you may get 429 errors under heavy usage. ↓

fix Set `Config.email = 'your@email.com'` at the start of your script to get a higher rate limit and polite usage.

deprecated The `works()` function (lowercase) is deprecated in favor of `Works` class (uppercase). The old function may be removed in a future version. ↓

fix Replace `from pyalex import works; works()...` with `from pyalex import Works; Works()...`.

gotcha When using `.search()` with multiple filters, ensure you chain them correctly. Filters like `filter={'year': 2020}` and `search='term'` are applied as separate calls, not combined in one filter dict. ↓

fix For combined filters, use `.filter()` with a single dict, e.g., `Works().filter({'year': 2020, 'is_oa': True}).get()`.

Install

pip install git+https://github.com/J535D165/pyalex.git

Imports

Works
wrong
```
from pyalex.Works import Works
```
correct
```
from pyalex import Works
```
Works is a top-level class, not a submodule. The incorrect import will raise ModuleNotFoundError.
Authors
wrong
```
import pyalex.Authors
```
correct
```
from pyalex import Authors
```
Common mistake: trying to import as a module instead of a class.
Config
```
from pyalex import Config
```
Config is used to set API key and email, e.g., Config.email = 'your@email.com'.

Quickstart

Basic usage: fetch a single work by ID and perform a search query.

from pyalex import Works, Config
import os

# Configure email (optional but recommended for polite API usage)
Config.email = os.environ.get('OPENALEX_EMAIL', 'you@example.com')

# Fetch a work by OpenAlex ID
work = Works()['W2741809807']
print(work['title'])

# Search for works
for work in Works().search('machine learning').get():
    print(work['title'])
    break