Registry / data / sec-edgar-downloader

sec-edgar-downloader

library5.1.0pypypi✓ verified 84d ago

sec-edgar-downloader is a Python package designed for efficiently downloading company filings from the SEC EDGAR database. Currently at version 5.1.0, it underwent a full rewrite in 5.0.0 to leverage the SEC's official EDGAR API and integrates formal rate-limiting using `pyrate-limiter` to comply with SEC fair access policies (10 requests per second). The library actively maintains support for recent Python versions and has a consistent release cadence with new features and fixes.

data

pip install sec-edgar-downloader

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · SEC-EDGAR-DOWNLOAD

sec-edgar-downloader

datapythonv5.1.0

Install

2.2s avg

Import

982ms

Disk

20MB

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.1.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 1.052s · 21.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.2s · import 0.911s · 22MB

20MB installed

● package 20MB

Code

Verified usage

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

Downloader

✓ from sec_edgar_downloader import Downloader

Initialize the `Downloader` with a valid company name and email address as your `User-Agent` (critical for SEC compliance) and then use the `get()` method to download filings by form type and ticker/CIK. The example demonstrates downloading a single 10-K filing and multiple 8-K filings after a certain date.

import os from sec_edgar_downloader import Downloader # It's crucial to set a User-Agent to comply with SEC's fair access policy. # Replace with your company name and admin contact email. # Example: 'MyCompanyName AdminContact@mycompany.com' company_name = os.environ.get('SEC_EDGAR_COMPANY_NAME', 'My Test Company') email_address = os.environ.get('SEC_EDGAR_EMAIL', 'test@example.com') # Initialize a downloader instance. Filings will be saved to the current working directory by default. # You can specify a different download_folder: dl = Downloader(company_name, email_address, '~/sec_filings') dl = Downloader(company_name, email_address) try: # Download the latest 10-K filing for Apple (AAPL) # The 'limit' parameter controls the number of most recent filings to download. count = dl.get('10-K', 'AAPL', limit=1) print(f"Successfully downloaded {count} filing(s) for AAPL.") # Download all 8-K filings for Microsoft (MSFT) after a specific date count = dl.get('8-K', 'MSFT', after='2023-01-01') print(f"Successfully downloaded {count} 8-K filing(s) for MSFT after 2023-01-01.") except Exception as e: print(f"An error occurred: {e}") print("Ensure your User-Agent is properly set and you are not exceeding SEC rate limits.")

sec-edgar-downloader --version

Debug

Known issues

breakingVersion 5.1.0 dropped support for Python 3.8 and 3.9. The package now requires Python 3.10 or higher.

fix

Upgrade your Python environment to version 3.10, 3.11, 3.12, 3.13, or 3.14.

affects: >=5.1.0

breakingVersion 5.0.0 involved a full package rewrite to utilize the SEC's new official EDGAR API. Code written for versions prior to 5.0.0 may no longer be compatible due to significant API changes.

fix

Review the official documentation and update your code to the new API patterns, especially for `Downloader` initialization and method calls.

affects: >=5.0.0

breakingVersion 5.1.0 upgraded `pyrate-limiter` from 3.x to 4.x. If you were using custom rate-limiting decorators or directly interacting with `pyrate-limiter`'s API, the `raise_when_fail` and `max_delay` parameters have been removed from `Limiter` initialization, and the decorator pattern changed from `@limiter(mapping_function)` to `@limiter.as_decorator(name='...', weight=1)`.

fix

Adjust any custom `pyrate-limiter` configurations or decorators to align with the 4.x API. The library's internal rate limiting remains functionally the same.

affects: >=5.1.0

gotchaThe SEC requires a specific `User-Agent` header for programmatic access, formatted as 'Company Name AdminContact@YourDomain.com'. Failing to provide a valid `User-Agent` during `Downloader` initialization will result in 403 Forbidden errors.

fix

Always initialize `Downloader(company_name, email_address, ...)` with a legitimate company name and a valid email address. This information is used to construct the compliant User-Agent.

affects: All versions

gotchaThe SEC imposes a fair access policy of 10 requests per second. The library includes internal rate-limiting, but aggressive or improperly configured usage (e.g., in parallel processes without proper synchronization) can still lead to temporary IP blocks (403 Forbidden errors) from the SEC.

fix

Rely on the library's built-in rate limiter. If making highly concurrent requests, ensure your application respects the 10 requests/second limit across all operations to `sec.gov`.

affects: All versions

Errors

Common errors & fixes

HTTPError: 403 Client Error: Forbidden for url: https://www.sec.gov/...

The SEC server rejected the request, usually due to a missing or invalid `User-Agent` header, or exceeding the rate limit (10 requests/second).

fix

Ensure the `Downloader` is initialized with valid `company_name` and `email_address` parameters. For example: `dl = Downloader('My Company', 'me@example.com')`. Avoid making excessive requests outside the library's internal rate limiting.

TypeError: Downloader.__init__() got an unexpected keyword argument 'user_agent'

In versions 5.0.0 and later, the `user_agent` parameter in the `Downloader` constructor was replaced by separate `company_name` and `email_address` parameters to explicitly comply with SEC requirements.

fix

Update your `Downloader` initialization from `Downloader(user_agent='...', ...)` to `Downloader(company_name='...', email_address='...', ...)`.

AttributeError: 'Downloader' object has no attribute 'get_filings_by_period'

Version 5.0.0 was a complete rewrite, and many older methods (like `get_filings_by_period` or parameters like `before_date`/`after_date` instead of `before`/`after`) were removed or renamed.

fix

Consult the latest documentation for `sec-edgar-downloader` (version 5.x.x) and update your code to use the current `get()` method signature and available parameters.

ImportError: cannot import name 'Downloader' from 'sec_edgar_downloader'

This usually indicates an installation issue, or the environment is picking up an older, incompatible version of the library.

fix

Ensure the package is correctly installed with `pip install -U sec-edgar-downloader` and that your Python environment is clean and correctly configured to use the installed package.

Upgrade

Version history

5.1.0latest on PyPI · released Feb 2, 2026

Audit

Dependencies

pyrate-limiterrequiredUsed for internal rate limiting to comply with SEC's fair access policy of 10 requests per second.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jadchaar/sec-edgar-downloader ↗

packagehttps://pypi.org/project/sec-edgar-downloader/ ↗

docshttps://sec-edgar-downloader.readthedocs.io ↗