Skip to main content

Python client to download IMF World Economic Outlook (WEO) dataset as pandas dataframes.

Project description


Open in Streamlit pytest Downloads

This is a Python client to download IMF World Economic Outlook Report dataset as pandas dataframes by release dates. You can explore:

  • single country macroeconomic data and forecast,
  • macro variables across countries for a given year,
  • country-year panel for single macro variable.

Dataset releases (vintages) are available back to 2007, the reported data goes back to 1980, forecast is three years ahead.



The program is tested to run under Python 3.8. It may work well with Python version 3.6 and above.

To install weo:

pip install weo

Step 1. Download data

You need to save data as from IMF web site as local file. Specify year and release:

import weo, release="Oct", filename="weo.csv")

You can access WEO releases starting October 2007 with this client. WEO is normally released in April and October, one exception is September 2011.

Release is referenced by number (1 or 2) or by month ('Apr' or 'Oct', and 'Sep' in 2011).

Your can list all years and releases available for download with weo.all_releases(). Combine it to create local dataset of WEO vintages from 2007 to present:

from weo import all_releases

for (year, release) in all_releases():, release, directory='weo_data') 

Note that folder 'weo_data' must exist for this script to run.

Step 2. Inspect data

Use WEO class to view and extract data. WEO is a wrapper around a pandas dataframe that ensures proper data import and easier access and slicing of data.

Try code below:

from weo import WEO

w = WEO("weo.csv")

What variables and measurements are inside?

# variable listing

# units
w.units("Gross domestic product, current prices")

# variable codes

# countries
w.countries("United")      # Dataframe with United Arab Emirates, United Kingdom
                           # and United States
w.iso_code3("Netherlands") # 'NLD'

The dataset is year-country-variable-value cube, you can fix any dimension to get a table.

w.get("General government gross debt", "Percent of GDP")

Plot a chart with the projected 12 largest economies in 2024 (current prices):

  .barh(title="GDP by country, USD billion (2024)")

Get GDP per capita data from 2000 to 2020:

w.gdp_pc_usd(start_year=2000, end_year=2020)

Alternative data sources

1. If you need the latest data as time series and not the vintages of WEO releases, and you know variables that you are looking for, dbnomics is a good choice:

Small example:

from dbnomics import fetch_series_by_api_link
ts1 = fetch_series_by_api_link(""

2. Similar dataset, not updated since 2018, but with earlier years:

Development notes

  • You can download the WEO file in command line with curl command:
curl -o weo.csv
  • WEOOct2020all.xls from the web site is really a CSV file, not an Excel file.
  • There is an update of GDP figures in June 2020, but the file structure is incompatible with regular releases.
  • Prior to 2020 the URL was similar to

Project details

Download files

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

Files for weo, version 0.6.3
Filename, size File type Python version Upload date Hashes
Filename, size weo-0.6.3-py3-none-any.whl (9.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size weo-0.6.3.tar.gz (9.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page