Skip to content
Back to search

edgartools

Read and analyze SEC EDGAR filings in Python. 10-K, 8-K, XBRL financials, Form 3/4/5, 13F, ADV — clean API, well-typed, MIT-licensed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dgunning/edgartools with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dgunning/edgartools'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dgunning--edgartools/badge.svg)](/listings/dgunning--edgartools)

HTML

<a href="/listings/dgunning--edgartools"><img src="/api/listings/dgunning--edgartools/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1. Install.** The package is `edgartools`; the module you import is `edgar`. Python 3.11+.

uv add edgartools        # or: pip install edgartools

**2. Identify yourself to the SEC.** EDGAR requires a contact email on every request. There is no key, signup or rate-limit tier.

from edgar import Company, set_identity

set_identity("your.name@example.com")

**3. Get data.**

# Five fiscal years of standardized income statement, from XBRL
Company("NVDA").income_statement(periods=5)
#> Total Revenue $215.9B $130.5B $60.9B

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 242 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <a href="https://github.com/dgunning/edgartools">
  2. <img src="https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/edgartools-mark.svg" alt="EdgarTools logo" align="left" height="80" hspace="20">
  3. </a>
  4. # EdgarTools — Python Library for SEC EDGAR Filings
  5. <br clear="left">
  6. <p>
  7. <a href="https://pypi.org/project/edgartools"><img src="https://img.shields.io/pypi/v/edgartools.svg" alt="PyPI - Version"></a>
  8. <a href="https://pypi.org/project/edgartools"><img src="https://img.shields.io/pypi/pyversions/edgartools.svg" alt="Python versions"></a>
  9. <a href="https://github.com/dgunning/edgartools/actions"><img src="https://img.shields.io/github/actions/workflow/status/dgunning/edgartools/python-hatch-workflow.yml" alt="Build status"></a>
  10. <a href="https://pepy.tech/project/edgartools"><img alt="Monthly downloads" src="https://static.pepy.tech/badge/edgartools/month"></a>
  11. </p>
  12. **EdgarTools** is a Python library for SEC EDGAR filings as structured data: financial statements, insider trades, fund holdings, proxy statements and dozens of other filing types, through one consistent Python API. SEC publishes every filing since 1994 for free, and almost none of it is ready to use; EdgarTools turns a filing into a typed Python object. Free and open source, MIT-licensed.
  13. **[Docs](https://edgartools.readthedocs.io/en/latest/)** · **[Cheat sheet](https://edgartools.readthedocs.io/en/latest/quick-guide/)** · Agents: **[Skill](https://edgartools.readthedocs.io/en/latest/ai/skills/)** · **[MCP server](https://edgartools.readthedocs.io/en/latest/ai/mcp-setup/)** · Hosted: **[edgar.tools](https://www.edgar.tools)**
  14. **EdgarTools 6.0** needs Python 3.11 or newer and renames or removes some 5.x APIs. Read [Upgrading to 6.0](https://edgartools.readthedocs.io/en/latest/upgrade/6.0/) before you upgrade, and [Upgrading to 6.1](https://edgartools.readthedocs.io/en/latest/upgrade/6.1/) for what changed since.
  15. ![EdgarTools SEC filing data extraction demo](https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/edgartools-demo.gif)
  16. ## Quick Start
  17. **1. Install.** The package is `edgartools`; the module you import is `edgar`. Python 3.11+.
  18. ```bash
  19. uv add edgartools # or: pip install edgartools
  20. ```
  21. **2. Identify yourself to the SEC.** EDGAR requires a contact email on every request. There is no key, signup or rate-limit tier.
  22. ```python
  23. from edgar import Company, set_identity
  24. set_identity("your.name@example.com")
  25. ```
  26. **3. Get data.**
  27. ```python
  28. # Five fiscal years of standardized income statement, from XBRL
  29. Company("NVDA").income_statement(periods=5)
  30. #> Total Revenue $215.9B $130.5B $60.9B
  31. ```
  32. ## Why not just call SEC's APIs?
  33. `data.sec.gov` gives you JSON facts and filing indexes. Everything past that is your code. EdgarTools does that part:
  34. - **Section text and markdown.** Item 1A, Item 7 or any Item of a 10-K or 10-Q as text, and whole filings as markdown for RAG. Raw HTML is where hand-rolled parsers break.
  35. - **Parsed forms, not XML.** 13F holdings, Form 4 transactions, N-PORT portfolios and 8-K items as typed objects and DataFrames.
  36. - **Statements that line up.** Rows standardized across filers, so "Total Revenue" means the same thing for a bank and a chipmaker, plus discrete quarters (Q4 derived from the 10-K) and trailing twelve months.
  37. - **Search and plumbing.** Full-text search over filing content, the live filing feed, rate limiting, caching and offline storage.
  38. It runs in your own process, MIT-licensed, with no API key and no vendor quota; SEC's fair-access limit of 10 requests a second still applies, and EdgarTools keeps to it.
  39. ## What you can do
  40. ### Full-text search across SEC filings
  41. Search the text of every filing since 2001, not just form types and dates.
  42. ```python
  43. from edgar import search_filings
  44. # Every 10-K filed since 2025 that mentions tariffs
  45. results = search_filings("tariff", forms="10-K", start_date="2025-01-01")
  46. hit = results[0]
  47. hit.accession_number, hit.form, hit.filed, hit.company # a hit's fields; filed is the filing date
  48. hit.get_filing() # the Filing behind a hit, ready for .obj() or .markdown()
  49. # Structured: 8-Ks that reported a cybersecurity incident (Item 1.05) in 2025
  50. search_filings(forms="8-K", items="1.05", start_date="2025-01-01", end_date="2025-12-31")
  51. #> 19 total
  52. ```
  53. [Full-text search guide →](https://edgartools.readthedocs.io/en/latest/guides/full-text-search/)
  54. ### Financial statements over several years
  55. ```python
  56. Company("MSFT").income_statement(periods=10) # also .balance_sheet() and .cash_flow_statement()
  57. ```
  58. [Financial Statements guide →](https://edgartools.readthedocs.io/en/latest/guides/financial-data/)
  59. ### One metric across companies
  60. Pick rows by their standardized label, never by position: the first row of an income statement is not always total revenue.
  61. ```python
  62. import pandas as pd
  63. revenue = {
  64. ticker: Company(ticker).income_statement(periods=3, as_dataframe=True)
  65. .set_index("label").filter(like="FY").loc["Total Revenue"] / 1e9
  66. for ticker in ["JPM", "PFE", "CAT"]
  67. }
  68. pd.DataFrame(revenue).round(1) # $ billions
  69. #> FY 2025 182.4 62.6 67.6
  70. ```
  71. ### Quarterly figures and trailing twelve months
  72. ```python
  73. nvda = Company("NVDA")
  74. nvda.get_ttm_revenue() # the last four quarters, summed
  75. nvda.income_statement(period="quarterly", periods=8) # discrete quarters; Q4 is derived from the 10-K
  76. ```
  77. ### Sections and markdown for RAG
  78. ```python
  79. filing = Company("NVDA").latest("10-K")
  80. filing.markdown() # the whole filing as markdown
  81. tenk = filing.obj()
  82. tenk.risk_factors # Item 1A as text
  83. tenk["Item 1C"] # any Item by number
  84. ```
  85. [Sections guide →](https://edgartools.readthedocs.io/en/latest/concepts/data-objects/)
  86. ### Find filings, by anything
  87. ```python
  88. from edgar import find, get_current_filings, get_filings
  89. get_filings(2025, 4, form="10-K") # every 10-K filed in Q4 2025
  90. get_current_filings() # the live feed, as SEC posts it
  91. find("0000320193-25-000079") # an accession number, CIK or ticker
  92. ```
  93. [Finding filings guide →](https://edgartools.readthedocs.io/en/latest/guides/searching-filings/)
  94. ![find() resolving a ticker, a CIK and an accession number](https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/universal-find.gif)
  95. ![get_current_filings() showing the live SEC filing feed](https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/live-filings.gif)
  96. ### 13F institutional holdings
  97. ```python
  98. thirteenf = Company("BRK.A").get_filings(form="13F-HR").latest().obj()
  99. thirteenf.holdings # one row per security: Issuer, Cusip, Ticker, SharesPrnAmount, Value, ...
  100. ```
  101. [Institutional Holdings guide →](https://edgartools.readthedocs.io/en/latest/guides/thirteenf-data-object-guide/)
  102. ![Berkshire Hathaway's latest 13F holdings](https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/thirteenf-holdings.gif)
  103. ### Insider trades from Form 4
  104. ```python
  105. form4 = Company("TSLA").get_filings(form="4").latest().obj()
  106. form4.to_dataframe() # buys, sells, grants and exercises
  107. ```
  108. [Insider Trades guide →](https://edgartools.readthedocs.io/en/latest/insider-filings/)
  109. ![Tesla's latest Form 4 parsed into a structured object](https://raw.githubusercontent.com/dgunning/edgartools/main/docs/images/insider-form4.gif)
  110. ### Fund holdings from N-PORT
  111. ```python
  112. from edgar import Fund
  113. Fund("VOO").get_portfolio() # the latest N-PORT holdings as a DataFrame
  114. ```
  115. [Fund Portfolios guide →](https://edgartools.readthedocs.io/en/latest/guides/nport-data-object-guide/)
  116. ### 8-K events and earnings releases
  117. ```python
  118. eightk = find("0001045810-26-000073").obj() # NVIDIA, 2026-08-26
  119. eightk.items # ['Item 2.02', 'Item 9.01']
  120. eightk.earnings # the EX-99.1 press release tables, parsed
  121. ```
  122. [Current Events guide →](https://edgartools.readthedocs.io/en/latest/eightk-filings/)
  123. ## Library or hosted?
  124. **EdgarTools** is this library: free, MIT-licensed, running in your own Python process. **[edgar.tools](https://www.edgar.tools)** is the hosted platform built on it: the same parsing, kept running and current, with every answer cited to its filing. You are not paying for the parsing; you are paying for it to be run and answerable. No feature is ever removed from the library to sell the platform.
  125. | If you want to… | Use |
  126. |---|---|
  127. | Build something that runs: pipelines, backfills, backtests, model corpora, notebooks, custom joins, anything repeated across hundreds of names or run inside your own network | **The library** |
  128. | Ask, not build: what the companies you cover filed and what changed since last time, who sold, who holds it, one person across every company they touch, screens across a universe, alerts, cited answers to forward or share with a team. From a browser, a phone, Excel, Claude or ChatGPT, or an agent that cannot run Python | **[edgar.tools](https://app.edgar.tools)**. Free account to start |
  129. | Own a maintained dataset (insider trades, 13F, BDC portfolios, material events), every row traceable to its filing, without running the pipeline | **[edgar.tools data licensing](https://www.edgar.tools/data)** |
  130. | Fetch one known filing or one JSON document, once, from a script | **Neither**: call EDGAR directly |
  131. Both have an MCP server: the library's runs locally (see AI Integration below), and edgar.tools' is hosted at [app.edgar.tools/mcp](https://app.edgar.tools/mcp). Attach one per client, not both: they overlap and split your assistant's routing.
  132. ## AI integration
  133. EdgarTools ships an agent skill and a local MCP server, both in the `ai` extra. For an assistant that cannot run Python, use the hosted connector from the section above instead.
  134. ```bash
  135. pip install "edgartools[ai]"
  136. python -c "from edgar.ai import install_skill; install_skill()" # the skill, for Claude Code and Claude Desktop
  137. ```
  138. The MCP server works with any MCP client. For Claude Desktop, add it to `claude_desktop_config.json`:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "edgartools": {
  143. "command": "uvx",
  144. "args": ["--from", "edgartools[ai]", "edgartools-mcp"],
  145. "env": {
  146. "EDGAR_IDENTITY": "Your Name your.email@example.com"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. `uvx` needs [uv](https://docs.astral.sh/uv/); without it, `pip install "edgartools[ai]"` and run `python -m edgar.ai`. Setup for other clients: [MCP server guide](https://edgartools.readthedocs.io/en/latest/ai/mcp-setup/) · [Skill guide](https://edgartools.readthedocs.io/en/latest/ai/skills/).
  153. ## Support the project
  154. The SEC changes filing formats and ships a new XBRL taxonomy every year. Sponsorship is what keeps the parsers current and pays for new ones as new disclosures appear.
  155. - **[GitHub Sponsors](https://github.com/sponsors/dgunning)**: monthly or one-time. Companies can sponsor on their existing GitHub bill.
  156. - **[Buy Me a Coffee](https://www.buymeacoffee.com/edgartools)**: a one-time thank-you.
  157. - **[Consulting](https://www.edgar.tools/consulting)**: help from the library's author with SEC data pipelines and financial AI built on it.
  158. <p align="center">
  159. <a href="https://github.com/sponsors/dgunning" target="_blank">
  160. <img src="https://img.shields.io/badge/Sponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=EA4AAA" alt="Sponsor on GitHub" height="44">
  161. </a>
  162. &nbsp;&nbsp;
  163. <a href="https://www.buymeacoffee.com/edgartools" target="_blank">
  164. <img src="https://img.shields.io/badge/Buy_me_a_coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black" alt="Buy Me A Coffee" height="44">
  165. </a>
  166. </p>
  167. ## Docs, help and contributing
  168. - [Documentation](https://edgartools.readthedocs.io/en/latest/) · [Cheat sheet](https://edgartools.readthedocs.io/en/latest/quick-guide/) · [Notebooks](https://edgartools.readthedocs.io/en/latest/notebooks/) · [Blog](https://www.edgartools.io)
  169. - Questions go to [Discussions](https://github.com/dgunning/edgartools/discussions); bugs and feature requests to [Issues](https://github.com/dgunning/edgartools/issues).
  170. - Contributions are welcome, including AI-assisted ones. Read the [contributing guide](https://github.com/dgunning/edgartools/blob/main/CONTRIBUTING.md) and point your assistant at [AGENTS.md](https://github.com/dgunning/edgartools/blob/main/AGENTS.md).
  171. EdgarTools is distributed under the [MIT License](https://github.com/dgunning/edgartools/blob/main/LICENSE.txt).
  172. <!-- mcp-name: io.github.dgunning/edgartools -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.