IRS API Python Client

N/A · maintenance · verified Tue Apr 07

Unofficial Python wrapper for accessing IRS (Internal Revenue Service) public data and tax-related information programmatically. Provides convenience methods for retrieving tax forms, instructions, and other IRS public resources.

Common errors

```
ModuleNotFoundError: No module named 'irs_api'
```
cause The `irs-api` library or its dependencies are not installed in the Python environment you are currently using, or the package name is misspelled.

fix Ensure the library is installed using pip: `pip install irs-api` or `pip install irs-api --upgrade` if it's already installed and you suspect a version issue.
```
requests.exceptions.ConnectionError: Max retries exceeded with url
```
cause The program failed to establish a connection with the IRS data source, often due to network issues, an incorrect URL, or the remote server being unavailable or refusing the connection.

fix Check your internet connection, verify the URL or endpoint being accessed by the library, and ensure no firewalls or proxies are blocking the request. The IRS server might also be temporarily down.
```
KeyError: 'some_data_field'
```
cause The program attempted to access a key (data field) in a dictionary-like API response that does not exist or has a different name than expected. This often happens if the IRS API's response structure has changed or the requested data is not available.

fix Inspect the actual JSON or dictionary response from the API to confirm the available keys. Update your code to use the correct key names or implement error handling for missing keys (e.g., using `.get('key', default_value)`).

Warnings

gotcha The pip package name is irs-api but the import module uses an underscore: irs_api. Using 'import irs_api' not 'import irs-api'.
Fix: from irs_api import IRS
gotcha This is an unofficial wrapper around publicly available IRS data. It is not endorsed or maintained by the IRS. Endpoints may break if the IRS changes their public website structure.
Fix: Implement retry logic and fallback handling in case upstream IRS data sources change.
deprecated The package has not been updated frequently. The last PyPI release is 0.0.3. API surface may be limited or stale.
Fix: Check the GitHub repository for any open issues or forks with more recent updates before relying on this in production.
gotcha Rate limiting or IP blocking may occur if too many requests are made to IRS endpoints in a short period.
Fix: Add delays between requests using time.sleep() and cache results locally to minimize repeated calls.

Install

pip install requests HTTP client (no official PyPI package)

Imports

IRS
wrong:
```
from irs import IRS
```
correct:
```
from irs_api import IRS
```
The package name on PyPI is irs-api but the Python module is irs_api (with underscore).

Quickstart

IRS public APIs are REST-only (no PyPI package). Endpoints vary by service. Always check Content-Type before calling .json() — some endpoints return HTML error pages on failure.

import requests

# IRS provides several public REST APIs (no key required for most)
# Forms and publications search
resp = requests.get(
    "https://www.irs.gov/api/forms-pubs/1040",
    headers={"Accept": "application/json"}
)
# IRS APIs may return HTML on error — check content-type before parsing
if resp.ok and "application/json" in resp.headers.get("Content-Type", ""):
    print(resp.json())
else:
    print(f"Status: {resp.status_code}")

view raw JSON →