Installation
Requirements
Python 3.10+
SQLite with FTS5 support (included in most Python installations)
~300 GB disk space for full database
Install from PyPI
pip install openalex-local
With optional dependencies:
# Server mode (FastAPI relay)
pip install openalex-local[server]
# MCP integration
pip install openalex-local[mcp]
# All features
pip install openalex-local[all]
Install from Source
git clone https://github.com/ywatanabe1989/openalex-local
cd openalex-local && pip install -e ".[all]"
Database Setup
The database can be set up in several ways:
Option 1: Environment Variable
export OPENALEX_LOCAL_DB=/path/to/openalex.db
Option 2: Default Locations
The package searches these locations automatically:
./openalex.db(current directory)~/openalex.db(home directory)~/.openalex/openalex.db
Option 3: Build from Scratch
Building the full database requires ~300 GB disk space:
# Check system status
make status
# 1. Download OpenAlex Works snapshot (~300GB)
make download-screen # runs in background
# 2. Build SQLite database
make build-db
# 3. Build FTS5 index
make build-fts
HTTP Mode (No Local Database)
Connect to a remote server instead of using a local database.
On the server (with database):
openalex-local relay --port 31292
On your machine:
# Option 1: SSH tunnel
ssh -L 31292:127.0.0.1:31292 your-server
# Option 2: Set environment variable
export OPENALEX_LOCAL_API_URL=http://server-ip:31292
export OPENALEX_LOCAL_MODE=http
The CLI and Python API work identically in both modes.
Verify Installation
# Check version
openalex-local --version
# Check status and configuration
openalex-local status
Environment Variables
Variable |
Description |
Default |
|---|---|---|
|
Path to SQLite database |
Auto-detect |
|
Force mode: |
Auto |
|
API URL for HTTP mode |
|
|
Server port |
|
|
Server host |
|