v0.17.0

2026-04-02

Highlights

This release introduces a unified virtualization API, replaces the previous open_virtual_dataset() / open_virtual_mfdataset() / consolidate_metadata() functions with a single virtualize() method compatible with VirtualiZarr 2.x, and opens support to most parsers (dmrpp, hdf, netcdf, kerchunk). It also adds FutureWarning deprecation notices in preparation for the upcoming v1.0 release. We improved download() by using temporary files until the files are complete and added a kwarg force to download and replace existing files. A new interface was added to the granules __geo_interface__ that allows libraries that support geojson geometries to access the UMM geometry of each granule, libraries like geopandas can then use the results to create a dataframe that can be plotted using such geometries.

import earthaccess as ea
import geopandas as gpd

ea.login()

granules = ea.search_data(**params)

# virtualization with one line, using dask or lithops and vz 2.x:
vds = ea.virtualize(granules, **vz_options)

# geo dataframes!
g_df = gpd.GeoDataFrame(geometry=granules, crs="EPSG:4326")

---

Breaking Changes

• Virtualization API overhaul: consolidate_metadata(), open_virtual_dataset(),
  and open_virtual_mfdataset() have been removed in favor of a single
  virtualize() method that supports all VirtualiZarr 2.x parsers (dmrpp, hdf,
  netcdf, kerchunk).
  (#1272)
  (@betolink)

Changed

• While downloading, files now use temporary names until the download completes,
  preventing partial files from being mistaken for complete downloads.
  (#1198)
  (@WeatherGod)

Added

• FutureWarning added to DataCollections and DataGranules methods decorated
  with @property, in preparation for the merge of #1187 in version 1.0.
  (#1267)
  (@andypbarrett)
• force kwarg added to download() to allow forced re-downloads.
  (#1198)
  (@WeatherGod)
• DataGranule.__geo_interface__ property for GeoJSON-compatible geometry access.
  (#1179)
  (@s-kganz)

Removed

• consolidate_metadata(), open_virtual_dataset(), and
  open_virtual_mfdataset() — replaced by virtualize().
  (#1272)
  (@betolink)

---

Documentation

• Build docs faster.
  (#1205)
  (@mfisher87)
• Add community calendar to "How to collaborate" page.
  (#1202)
  (@mfisher87)
• Simplify PR template.
  (#1210)
  (@mfisher87)
• Add logo to repository.
  (#1208)
  (@mfisher87)
• Decision: "Repotting" earthaccess to a new organization.
  (#1047)
  (@mfisher87)
• Mention the PR template in PR docs.
  (#1218)
  (@mfisher87)
• Turn on mkdocs strict mode and check for broken links.
  (#1209)
  (@mfisher87)
• Fix broken notebooks.
  (#1211)
  (@mfisher87)
• Enable docs navigation breadcrumbs.
  (#1222)
  (@mfisher87)
• Re-organize docs into top-level user/contributor sections.
  (#1212)
  (@mfisher87)
• Add "Edit this page" button to every docs page.
  (#1221)
  (@mfisher87)
• Fix broken links.
  (#1224,
  #1258)
  (@mfisher87)
• Move community calendar to docs front page.
  (#1232)
  (@mfisher87)
• Remove redundant information from document title.
  (#1233)
  (@mfisher87)
• ESIP Funding Friday song lyrics.
  (#1056)
  (@stefaniebutland)
• Include ESIP funding friday lyrics as a link from the index.
  (#1262)
  (@itcarroll)
• Soften test/CI language and encourage asking for help.
  (#1273)
  (@danielfromearth)
• Add entries to citation file.
  (#1254)
  (@danielfromearth)
• Add earthaccess repotting history.
  (#1239)
  (@JessicaS11)
• Update last updated date in 929-move-repository.md.
  (#1248)
  (@asteiker)

---

New Contributors

• @WeatherGod made their first contribution in #1198
• @s-kganz made their first contribution in #1179
• @ateucher made their first contribution in #1240
• @stefaniebutland made their first contribution in #1056
• @zkoppert made their first contribution in #1278

Full Changelog: v0.16.0...v0.17.0

v0.16.0

Changed

• Improved performance of fetching temporary S3 credentials (roughly 4x speedup) by using EDL user token rather than EDL username/password in request (#1182) (@chuckwondo)
• open_virtual_datasets now accepts load=False to avoid materializing indexes when they are not needed (e.g. xarray pre-processing metadata) (#1185) (@betolink)

Added

• Added methods doi and citation to DataCollection class. (#203) (@Sherwin-14, @chuckwondo)

Removed

• Breaking: Remove default automatic login behavior. This removes previously undocumented behavior, where a user would be logged in automatically (i.e., without having to call earthdata.login explicitly) if the user had valid EDL credentials specified either via environment variables or a netrc file. This led to potentially unexpected behavior.

  Removing this automatic behavior breaks existing user code that does not make an explicit call to earthdata.login before streaming/downloading data, but used to succeed due to the (perhaps unknown) automatic login behavior.

  Users must now explicitly call earthdata.login in order to access data that requires EDL authentication.

  Removing this automatic behavior was necessary to fix #945.

Fixed

• Ignore environment variables EARTHDATA_USERNAME and EARTHDATA_PASSWORD when EARTHDATA_TOKEN is set (#1121) (@chuckwondo)
• Use only specified login strategy to attempt login, when strategy other than "all" is specified (#945) (@chuckwondo)
• Fix undesirable pre-commit changes when running on Windows (#1143) (@ana-sher)
• No longer erroneously strip authorization header for valid hosts (#1130) (@chuckwondo)
• Fix AttributeError raised by Auth.get_s3_credentials when EARTHDATA_TOKEN environment variable is set, which prevented the username attribute from being defined on the Auth instance (#1181) (@chuckwondo)

New Contributors

• @tsutterley made their first contribution in #1101
• @ana-sher made their first contribution in #1144

Full Changelog: v0.15.1...v0.16.0

v0.15.1

📣 📣 📣 Bug Fix 📣 📣 📣

• Patch to avoid import errors with VirtualiZarr/Obstore.

What's Changed

• fix virtualizarr imports by @betolink in #1098
• bump version patch 0.15.1 by @betolink in #1099

Full Changelog: v0.15.0...v0.15.1

v0.15.0

New features

Hide progress bar

files = earthaccess.open(results, show_progress=False)

Updated documentation, enhanced docsstrings and user guide documentation

Support for VirtualiZarr 2.x e.g. virtual Tempo data cube

faster fsspec caching and open kwargs:

fsspec_open_kwargs = {
  "cache_type": "blockcache", # cache strategy
  "block_size": 4 * 1024 * 1024 # bytes
}
files = earthaccess.open(results, open_kwargs=fsspec_open_kwargs)

This speeds up .open() by potentially an order of magnitude!

What's Changed

• Populated glossary section under USER-REFERENCE.
  (#1027)
  (@Sherwin-14)
• Change default cache behavior in fsspec from readahead to blockcache.
  Allow user defined config with open_kwargs in the .open() method.
  This improves performance by an order of magnitude.
  (#251)(#771)
  (@betolink)
• Add show_progress argument to earthaccess.download() to let the user control display of progress bars. Defaults to true for interactive sessions, otherwise false.
  (#612)
  (#1065)
  (@Sherwin-14)
• Updated bug and triage label names in bug Issue template.
  (#998)
  (@asteiker)
• download now raises DownloadFailure exception on failure.
  (#612)
  (@Sherwin-14)
• GESDISC should be GES_DISC in docstrings.
  (#1037)
  (@abarciauskas-bgse)
• open_virtual_mfdataset now uses virtualizarr v2, and obstore in place of fsspec. Updated Zarr to V3 xref #967.
  (#1074)
  (@owenlittlejohns)
• Populate search and access user guides.
  (#1035)
  (@andypbarrett)

New Contributors

• @weiji14 made their first contribution in #966
• @rwegener2 made their first contribution in #977
• @stelios-c made their first contribution in #994
• @kgrimes2 made their first contribution in #1020
• @jbusecke made their first contribution in #1067
• @mike-gangl made their first contribution in #971
• @owenlittlejohns made their first contribution in #1074
• @alexandervladsemenov made their first contribution in #1015

Full Changelog: v0.14.0...v0.15.0

v0.14.0

[v0.14.0] - 2025-02-11

📣 📣 📣 BREAKING CHANGE 📣 📣 📣

From now on, any time Earthdata Login rejects credentials, a Python exception will be raised. You can get the old behavior with a standard try/except block:

# Caution: If credentials are rejected, you should know about it and update any env vars
# or .netrc files. If credentials are rejected too many times, you could get locked out
# of your account.
try:
    earthaccess.login()
except Exception:
    pass

Added

• search_datasets now accepts a has_granules keyword argument. Use has_granules=False to search for metadata about collections with no associated granules. The default value set in DataCollections remains True. (#939) (@juliacollins)

Changed

• Breaking: earthaccess will now raise an exception when login credentials are rejected. If you need the old behavior, please use a try block. (#888) (@mfisher87, @chuckwondo, @jhkennedy)

New Contributors

• @juliacollins made their first contribution in #940

Full Changelog: v0.13.0...v0.14.0

v0.13.0

[v0.13.0] - 2025-01-28

Changed

• Integration tests: Test are no longer randomized! this means each fail should be reproducible, we are testing the most
  popular datasets from all DAACs, see files under tests/integration/popular_collections.
  (#215)
  (@mfisher87)

Added

• VirtualiZarr: earthaccess can open archival formats (NetCDF, HDF5) as if they were Zarr by leveraging VirtualiZarr
  In order to use this capability the collection needs to be supported by OPeNDAP and have dmrpp files.
  See example notebooks!
  (@ayushnag and @TomNicholas)

Fixed

• earthaccess.download will let requests automatically decode compressed content
  (#887)
  (@itcarroll)

• earthaccess.download now shares the authenticated session cookie among threads to avoid overloading EDL.
  (#913)
  (@hailiangzhang)

Complete autogenerated list:

What's Changed

• Refactor development guide by @jhkennedy in #874
• chore: update pre-commit hooks by @pre-commit-ci in #886
• Opening virtual datasets (dmr-adapter) by @ayushnag in #606
• Fix Incorrect Earthdata Login Hyperlinks by @mitchstartzel in #907
• Add a workflow for generating Hackday Github Discussion threads by @Sherwin-14 in #914
• Fix CATEGORY_ID in hack day discussion workflow by @mfisher87 in #917
• download using chunk iteration rather than raw response by @itcarroll in #920
• Fix small open_virtual_dataset bugs by @ayushnag in #923
• Thread-local Session Management and Cookie Reuse to Address EDL DSE issue by @hailiangzhang in #909
• NASA directive updates by @asteiker in #928
• Refactor integration tests to remove random collection sampling by @mfisher87 in #749
• Add earthaccess-virtualizarr tutorial notebook by @ayushnag in #904
• Preparing the release of v0.13.0 by @betolink in #931

New Contributors

• @ayushnag made their first contribution in #606
• @mitchstartzel made their first contribution in #907
• @hailiangzhang made their first contribution in #909

Full Changelog: v0.12.0...v0.13.0

v0.12.0

v0.12.0

Changed

• Use built-in assert statements instead of unittest assertions in integration tests (#743) (@chuckwondo)

Added

• Add support for NETRC environment variable to override default .netrc file location (#480) (@chuckwondo)
• Add nox session for running integration tests locally (#815; @chuckwondo and #872; @jhkennedy)
• Auto-add comment to PR that requires maintainer to review and re-run integration tests (#824) (@chuckwondo)

Removed

• The scripts/integration-test.sh script has been removed in favor of the integration-tests nox session. (#872) (@jhkennedy)
• Python 3.9 is no longer supported. (#876) (@mfisher87)

Fixed

• earthaccess.download will not ignore errors by default (#581) (@Sherwin-14, @chuckwondo, @mfisher87)
• Integration tests no longer clobber existing .netrc file (#806) (@chuckwondo)
• Return an empty list instead of raising an IndexError when searches find no results. (#526) (@jhkennedy)

Full Changelog: v0.11.0...v0.12.0

v0.11.0

v0.11.0

Changed

• Automatically refresh EDL token and deprecate the Auth.refresh_tokens method with no replacement, as there is no longer a need to explicitly refresh (#484) (@fwfichtner)
• Deprecate earthaccess.get_s3fs_session and Store.get_s3fs_session. Use earthaccess.get_s3_filesystem and Store.get_s3_filesystem, respectively, instead (#766) (@Sherwin-14, @chuckwondo)

Added

• Add Issue Templates (#281) (@Sherwin-14)
• Support Service queries (#447) (@nikki-t, @chuckwondo, @mfisher87, @betolink)
• Add example PR links to pull request template (#756) (@Sherwin-14, @mfisher87)
• Add Contributing Naming Convention document (#532) (@Sherwin-14, @mfisher87)

Fixed

• Remove broken link "Introduction to NASA earthaccess" (#779) (@Sherwin-14)
• Restore automation for tidying notebooks used in documentation (#788) (@itcarroll)

Removed

• Remove binder/ directory, as we no longer need a special binder environment with the top-level environment.yml introduced in #733 (@jhkennedy)

New Contributors

• @fwfichtner made their first contribution in #782
• @nikki-t made their first contribution in #500

Full Changelog: v0.10.0...v0.11.0

v0.10.0

v0.10.0

Changed

• Perform YAML formatting with yamlfmt instead of
  prettier (#555)
  (@chuckwondo,@mfisher87)
• Replace print calls with logging calls where appropriate and add T20 Ruff rule
  (#511)
  (@botanical,@chuckwondo,
  @mfisher87)
• Update CHANGELOG.md to follow Common Changelog conventions
  (#584)
  (@danielfromearth,@chuckwondo,
  @jhkennedy,@mfisher87)

Added

• Enable queries to Earthdata User Acceptance Testing (UAT) system for authenticated accounts
  (#421)
  (@danielfromearth,@mfisher87,
  @jhkennedy,@chuckwondo,
  @betolink)
• Add support for Python 3.12
  (#457)
  (@chuckwondo,@mfisher87)

Removed

• Breaking: Remove support for Python 3.8
  (#457)
  (@mfisher87,@chuckwondo)
• Breaking: Remove the
  get_user_profile method and the email_address and profile attributes
  from the Auth class. Calling the EDL API to get user profile information
  is not intended for library access and is not necessary for this library's
  intended use cases. (#421)
  (@danielfromearth,@mfisher87,
  @jhkennedy,@chuckwondo,
  @betolink)

Fixed

• Use Search After
  for collection and granule searches to support deep-paging through large result sets
  (#483)
  (@doug-newman-nasa,@chuckwondo,
  @mfisher87,@betolink)
• Correct and enhance static type hints for functions and methods that make CMR queries
  or handle CMR query results (#508)
  (@mfisher87,@jhkennedy,
  @chuckwondo,@betolink)
• Create destination path prior to direct S3 downloads, if it doesn't already
  exist (#562)
  (@itcarroll,@mfisher87,
  @chuckwondo)
  -Fix broken image link in sea level rise tutorial
  ((#427)(@jbrownrs)

New Contributors

• @battistowx made their first contribution in #492
• @chuckwondo made their first contribution in #497
• @doug-newman-nasa made their first contribution in #494
• @rupesh2 made their first contribution in #469
• @botanical made their first contribution in #566
• @Sherwin-14 made their first contribution in #579
• @jbrownrs made their first contribution in #753

Full Changelog: v0.9.0...v0.10.0

v0.9.0

What's Changed

• Features:

  • Allow datetime object to be provided for temporal queries by @vincentsarago in #451
  • Use pathlib in earthaccess.download() by @kvenkman in #459
  • earthaccess will send user-agent headers to track usage. #443
  • Search by instrument or project e.g. instrument="gedi" #443

• Bug fixes:

  • Fixed searching for restricted datasets #443
  • Fixed accessing Opera data behind custom endpoints (ASF) #443

• Maintenance:

  • Update README.md by @abarciauskas-bgse in #429
  • Clarify that temporal and bbox args must be tuples in docstrings, fix docstring formatting by @mfisher87, @danielfromearth in #448
  • Update CITATION.cff to fix Zenodo, add CFF validator by @mfisher87 in #408
  • Add workflow to update PRs with docs preview link in description by @mfisher87 in #414
  • Remove s3fs < 2024 pin by @rsignell in #466
  • Update README.md by @asteiker in #434

New Contributors

• @abarciauskas-bgse made their first contribution in #429
• @vincentsarago made their first contribution in #451
• @kvenkman made their first contribution in #459
• @rsignell made their first contribution in #466

Full Changelog: v0.8.2...v0.9.0