edgartools

library5.36.0pypypi✓ verified 87d ago

EdgarTools is a Python library designed to access and analyze SEC EDGAR filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports. It provides structured Python objects for over 20 filing types, converting complex SEC data into easy-to-use DataFrames. Currently at version 5.29.0, the library is actively developed with frequent updates addressing bug fixes and adding new features, often multiple releases per month.

data

pip install edgartools

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · EDGARTOOLS

edgartools

datapythonv5.36.0

Install

17.2s avg

Import

3732ms

Disk

405MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.36.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.920 runs

installs and imports cleanly · install 0.0s · import 3.884s · 421.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 17.2s · import 3.580s · 385MB

405MB installed

● package 405MB

Code

Verified usage

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

Company

✓ from edgar import Company

Primary class for looking up companies and their filings.

set_identity

✓ from edgar import set_identity

✗ from edgartools import set_identity

Most core components are imported directly from the `edgar` top-level namespace, not `edgartools`.

get_filings

✓ from edgar import get_filings

Used for fetching a broader range of filings not necessarily tied to a single company, or when working with Form 13F-HR.

This quickstart demonstrates how to set your SEC identity, create a `Company` object, access basic company information, and retrieve the latest income statement and balance sheet. It highlights the structured data access that edgartools provides.

import os from edgar import Company, set_identity # The SEC requires all API users to identify themselves with a name and email. # Set this once or use the EDGAR_IDENTITY environment variable. identity = os.environ.get('EDGAR_IDENTITY', 'John Doe john.doe@example.com') set_identity(identity) # Get a company by its ticker symbol company = Company("AAPL") # Access basic company data print(f"Company: {company.name}") print(f"Industry: {company.industry}") # Get the company's latest financial statements financials = company.get_financials() income_statement = financials.income_statement() balance_sheet = financials.balance_sheet() cashflow_statement = financials.cashflow_statement() print("\nLatest Income Statement (first 5 rows):\n", income_statement.head()) print("\nLatest Balance Sheet (first 5 rows):\n", balance_sheet.head())

edgar --version

Debug

Known issues

gotchaThe SEC requires all API users to identify themselves with a name and email. Failing to do so will result in an error when making requests.

fix

Call `edgar.set_identity("Your Name your.email@example.com")` once at the beginning of your script, or set the `EDGAR_IDENTITY` environment variable.

affects: All versions

gotchaThere is an unrelated package on PyPI also named `edgar`. Installing `edgar` instead of `edgartools` will lead to `ImportError`.

fix

Ensure you `pip install edgartools`. If you previously installed `edgar`, run `pip uninstall edgar && pip install edgartools`.

affects: All versions

gotchaPrior to v5.28.5, the `to_dataframe()` method for disclosure `TextBlock` concepts could contain raw HTML markup instead of plain text, leading to uncleaned data in DataFrames.

fix

Upgrade to edgartools v5.28.5 or newer to ensure HTML content in `TextBlock` disclosures is automatically sanitized to plain text.

affects: <5.28.5

gotchaBefore v5.28.3, financial statement quarter labels for companies with non-calendar fiscal years might have been incorrect, using hardcoded calendar months instead of the company's fiscal year end month.

fix

Upgrade to edgartools v5.28.3 or newer to get accurate quarter labels for non-calendar fiscal year companies.

affects: <5.28.3

gotchaThe SEC imposes rate limits (typically 10 requests per second) on EDGAR data access. Exceeding these limits can result in your IP being temporarily blocked.

fix

edgartools generally handles rate limiting internally, but for large-scale operations, enable local storage, batch downloads, and process filings sequentially or with careful parallel processing.

affects: All versions

deprecatedWhile `cash_flow_statement()` still works, the canonical method for retrieving cash flow statements is `cashflow_statement()` (without an underscore).

fix

Use `financials.cashflow_statement()` for consistency and to follow the canonical naming convention.

affects: v5.x

Errors

Common errors & fixes

ImportError: cannot import name 'get_filings' from 'edgar'

This error occurs when an older, unrelated Python package named 'edgar' is installed, conflicting with the `edgartools` library which uses `from edgar import ...` for its modules.

fix

First, uninstall the conflicting 'edgar' package, then install or reinstall 'edgartools'.
`pip uninstall edgar`
`pip install edgartools`

SEC Identity Error

The SEC requires a User-Agent string (your name and email) for all requests to identify the user, and `edgartools` enforces this requirement.

fix

Set your identity either programmatically or via an environment variable before making any requests.
`from edgar import set_identity`
`set_identity('Your Name your.email@company.com')`
Or via environment variable:
`export EDGAR_IDENTITY='Your Name your.email@company.com'` (Linux/macOS)

SSLCertVerificationError: certificate verify failed

This typically happens in corporate environments due to VPNs or SSL inspection proxies intercepting HTTPS traffic and re-signing certificates, which Python's bundled certificates may not trust.

fix

Configure `edgartools` to use your operating system's certificate store, which should include your corporate CA.
`from edgar import configure_http`
`configure_http(use_system_certs=True)`

AttributeError: 'Filing' object has no attribute 'financials'

This error occurs when attempting to access financial data directly from a generic `Filing` object. To access structured financial data, you need to first get the form-specific object (e.g., `TenK`, `TenQ`) or an XBRL object.

fix

Access the form-specific object using `.obj()` or the XBRL object using `.xbrl()` before accessing financial properties.
`tenk = filing.obj()`
`income_statement = tenk.financials.income_statement`
Or:
`xbrl_statements = filing.xbrl().statements`

Upgrade

Version history

5.36.0latest on PyPI · released Jun 9, 2026

Audit

Dependencies

pandasrequiredCore for data manipulation and DataFrame output.

httpxrequiredUsed for making HTTP requests to the SEC EDGAR database.

lxmlrequiredHigh-performance HTML and XML parsing for structured data extraction.

pyarrowrequiredUsed for optimized data handling, especially when working with DataFrames.

Agent activity

22 hits · last 30 days

node