imf-reader

Python access to IMF World Economic Outlook and Special Drawing Rights data.

imf-reader fetches two IMF datasets that are hard to reach programmatically, the World Economic Outlook (WEO) database and Special Drawing Rights (SDR) data, and returns them as tidy pandas DataFrames.

WEO data comes from the IMF's SDMX API for releases from April 2025 onward and from a discontinued bulk SDMX archive for everything before it, translated onto one vocabulary so columns and codes match across both sources. SDR daily valuation and weekly interest rates have no API, so imf-reader parses them from IMF web pages. SDR allocations and holdings do exist on the API at monthly frequency, but this package has not moved to it and still parses them from web pages too. Both sources make the package sensitive to changes in the IMF's site structure or file formats. Please report any issues you encounter.

Installation

pip install imf-reader

Or with uv:

uv add imf-reader

Or from conda-forge:

conda install imf-reader

Usage

Fetch WEO data and filter it, for example Nigeria's real GDP growth:

from imf_reader import weo

df = weo.fetch_data()
growth = df[
    (df.REF_AREA_CODE == "NGA")
    & (df.CONCEPT_CODE == "NGDP_RPCH")
    & (df.TIME_PERIOD.between(2020, 2024))
]
print(growth[["REF_AREA_LABEL", "TIME_PERIOD", "OBS_VALUE", "UNIT_LABEL"]].to_string(index=False))

Output:

REF_AREA_LABEL  TIME_PERIOD  OBS_VALUE UNIT_LABEL
       Nigeria         2020  -6.368898    Percent
       Nigeria         2021   1.109253    Percent
       Nigeria         2022   4.318829    Percent
       Nigeria         2023   3.315904    Percent
       Nigeria         2024   4.071067    Percent

Fetch SDR allocations and holdings:

from imf_reader import sdr

df = sdr.fetch_allocations_holdings()

This returns one row per entity per indicator, with entity, indicator (holdings or allocations), value, and date columns.

Versions, caching, and the full column reference for both datasets are covered in the documentation.

Documentation

Full documentation lives at docs.one.org/tools/imf-reader. Start with Why imf-reader for the motivation, Getting started for a first walkthrough, and the WEO and SDR guides for dataset-specific detail.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines. This project is released with a Code of Conduct. By contributing, you agree to abide by its terms.

License

imf-reader is licensed under the MIT license. It was created by Luca Picci and is maintained by the ONE Campaign.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imf_reader-2.1.0.tar.gz (42.7 kB view details)

Uploaded Aug 14, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

imf_reader-2.1.0-py3-none-any.whl (50.8 kB view details)

Uploaded Aug 14, 2026 Python 3

File details

Details for the file imf_reader-2.1.0.tar.gz.

File metadata

Download URL: imf_reader-2.1.0.tar.gz
Upload date: Aug 14, 2026
Size: 42.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for imf_reader-2.1.0.tar.gz
Algorithm	Hash digest
SHA256	`f3f36647138f858590a84b08a371bf6c2937284bc378e41269756b9435d7bb34`
MD5	`020ff239ab88ce28a3bbe5c0ab999315`
BLAKE2b-256	`7beb3676a1c2d57f1631d3a37dd4a536c19dc7729a1ccce9d5e8cf6035ebda82`

See more details on using hashes here.

Provenance

The following attestation bundles were made for imf_reader-2.1.0.tar.gz:

Publisher: release.yml on ONEcampaign/imf-reader

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: imf_reader-2.1.0.tar.gz
- Subject digest: f3f36647138f858590a84b08a371bf6c2937284bc378e41269756b9435d7bb34
- Sigstore transparency entry: 2466469286
- Sigstore integration time: Aug 14, 2026
Source repository:
- Permalink: ONEcampaign/imf-reader@8c95a058d8580f314b7bc63003b1b2d2d1e48540
- Branch / Tag: refs/tags/v2.1.0
- Owner: https://github.com/ONEcampaign
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@8c95a058d8580f314b7bc63003b1b2d2d1e48540
- Trigger Event: release