arxiv

library2.4.1pypypi✓ verified 52d ago

The `arxiv` library is a Python wrapper for the arXiv API, providing programmatic access to over a million scholarly articles in physics, mathematics, computer science, and other fields. It allows users to search, retrieve metadata, and download papers from the arXiv open-access repository. The library is actively maintained with frequent minor and patch releases.

data ai-ml

pip install arxiv

github ↗package ↗docs ↗

Install & Compatibility

Where this runs

tested against v4.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.930 runs

installs and imports cleanly · install 0.0s · import 0.693s · 33.4MB

glibc

py 3.10–3.930 runs

installs and imports cleanly · install 2.7s · import 0.623s · 34MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from arxiv import Client

✗ from arxiv.arxiv import Client

Submodule-style imports were deprecated in v2.1.0; direct import from `arxiv` is now the canonical way.

✓ from arxiv import Search

Result

✓ from arxiv import Result

SortCriterion

✓ from arxiv import SortCriterion

SortOrder

✓ from arxiv import SortOrder

This example demonstrates how to initialize the API client, perform a search for articles, and iterate through the results to print their titles, authors, and publication dates.

import arxiv # Construct the default API client client = arxiv.Client() # Search for the 10 most recent articles matching 'quantum' search = arxiv.Search( query = "quantum", max_results = 10, sort_by = arxiv.SortCriterion.SubmittedDate, sort_order = arxiv.SortOrder.Descending ) for result in client.results(search): print(f"Title: {result.title}") print(f"Authors: {', '.join(author.name for author in result.authors)}") print(f"Published: {result.published}") # Example: download PDF to current directory (note deprecation warning in v2.3.0) # result.download_pdf(dirpath='./downloads')

Debug

Known issues

breakingPython 3.7 and 3.8 are no longer officially supported as of version 2.2.0. While existing code might still run, CI validation has ceased for these versions, and future compatibility is not guaranteed.

fix

Upgrade to Python 3.9 or newer. The library officially supports Python 3.9 through 3.13.

affects: >=2.2.0

deprecatedSubmodule-style imports like `import arxiv.arxiv` or `from arxiv import arxiv` were deprecated in version 2.1.0.

fix

Use direct imports from the top-level `arxiv` package, e.g., `import arxiv` or `from arxiv import Client, Search`.

affects: >=2.1.0

deprecatedDirect download helper methods (e.g., `result.download_pdf()`, `result.download_source()`) were deprecated in version 2.3.0. While they might still function, their use is discouraged.

fix

Implement custom download logic using `result.pdf_url` or `result.links` to fetch content, or use a dedicated download manager.

affects: >=2.3.0

gotchaVersion 2.3.1 introduced a fallback for missing titles by string matching `/pdf/`, which was reverted in 2.3.2 due to potential issues. If you encountered unexpected title parsing behavior around this version, it might have been related to this change.

fix

Ensure you are on the latest patch release (>=2.3.2) to avoid the temporary fallback logic.

affects: 2.3.1

gotchaThe arXiv API requests that users 'make no more than one request every three seconds'. The library's `Client` can be configured with `delay_seconds` to respect this, but excessive unthrottled requests can lead to IP blocking by arXiv.

fix

When creating an `arxiv.Client`, consider setting `delay_seconds` (e.g., `client = arxiv.Client(delay_seconds=3.0)`) especially for scripts making many requests. Cache results where possible.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'arxiv'

The 'arxiv' library is not installed in the Python environment.

fix

pip install arxiv

ImportError: cannot import name 'Client' from 'arxiv'

The 'Client' class is not available in the 'arxiv' module, possibly due to an outdated version.

fix

Ensure you have the latest version of the 'arxiv' library installed: pip install --upgrade arxiv

AttributeError: module 'arxiv' has no attribute 'Search'

The 'Search' class is not found in the 'arxiv' module, likely due to an incorrect import or outdated library version.

fix

Verify the correct import statement: from arxiv import Search; and ensure the library is up to date: pip install --upgrade arxiv

TypeError: 'NoneType' object is not iterable

The 'arxiv' API returned no results, leading to an attempt to iterate over a 'None' object.

fix

Check the search query parameters to ensure they are valid and likely to return results.

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='export.arxiv.org', port=443): Max retries exceeded

Network issues or the arXiv API being down, causing connection attempts to fail.

fix

Verify your internet connection and check the arXiv API status; consider implementing retry logic with exponential backoff.

Upgrade

Version history

4.0.0latest on PyPI

Audit

Dependencies

requestsrequiredUsed for making HTTP requests to the arXiv API.

Agent activity

50 hits · last 30 days

node

seranking-bot

ahrefsbot

amazonbot

Google (AI)

Resources

githubhttps://github.com/lukasschwab/arxiv.py ↗

packagehttps://pypi.org/project/arxiv/ ↗

docshttps://lukasschwab.me/arxiv.py/ ↗