{"id":8627,"library":"sec-edgar-downloader","title":"SEC EDGAR Downloader","description":"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.","status":"active","version":"5.1.0","language":"en","source_language":"en","source_url":"https://github.com/jadchaar/sec-edgar-downloader","tags":["SEC","finance","filings","EDGAR","data-downloader","financial-data"],"install":[{"cmd":"pip install sec-edgar-downloader","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for internal rate limiting to comply with SEC's fair access policy of 10 requests per second.","package":"pyrate-limiter","optional":false}],"imports":[{"symbol":"Downloader","correct":"from sec_edgar_downloader import Downloader"}],"quickstart":{"code":"import os\nfrom sec_edgar_downloader import Downloader\n\n# It's crucial to set a User-Agent to comply with SEC's fair access policy.\n# Replace with your company name and admin contact email.\n# Example: 'MyCompanyName AdminContact@mycompany.com'\ncompany_name = os.environ.get('SEC_EDGAR_COMPANY_NAME', 'My Test Company')\nemail_address = os.environ.get('SEC_EDGAR_EMAIL', 'test@example.com')\n\n# Initialize a downloader instance. Filings will be saved to the current working directory by default.\n# You can specify a different download_folder: dl = Downloader(company_name, email_address, '~/sec_filings')\ndl = Downloader(company_name, email_address)\n\ntry:\n    # Download the latest 10-K filing for Apple (AAPL)\n    # The 'limit' parameter controls the number of most recent filings to download.\n    count = dl.get('10-K', 'AAPL', limit=1)\n    print(f\"Successfully downloaded {count} filing(s) for AAPL.\")\n\n    # Download all 8-K filings for Microsoft (MSFT) after a specific date\n    count = dl.get('8-K', 'MSFT', after='2023-01-01')\n    print(f\"Successfully downloaded {count} 8-K filing(s) for MSFT after 2023-01-01.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure your User-Agent is properly set and you are not exceeding SEC rate limits.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10, 3.11, 3.12, 3.13, or 3.14.","message":"Version 5.1.0 dropped support for Python 3.8 and 3.9. The package now requires Python 3.10 or higher.","severity":"breaking","affected_versions":">=5.1.0"},{"fix":"Review the official documentation and update your code to the new API patterns, especially for `Downloader` initialization and method calls.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Version 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)`.","severity":"breaking","affected_versions":">=5.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The SEC server rejected the request, usually due to a missing or invalid `User-Agent` header, or exceeding the rate limit (10 requests/second).","error":"HTTPError: 403 Client Error: Forbidden for url: https://www.sec.gov/..."},{"fix":"Update your `Downloader` initialization from `Downloader(user_agent='...', ...)` to `Downloader(company_name='...', email_address='...', ...)`.","cause":"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.","error":"TypeError: Downloader.__init__() got an unexpected keyword argument 'user_agent'"},{"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.","cause":"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.","error":"AttributeError: 'Downloader' object has no attribute 'get_filings_by_period'"},{"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.","cause":"This usually indicates an installation issue, or the environment is picking up an older, incompatible version of the library.","error":"ImportError: cannot import name 'Downloader' from 'sec_edgar_downloader'"}]}