Install & Compatibility
Where this runs
tested against v0.12.10b0 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 3.287s · 253.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.5s · import 3.138s · 242MB
256MB installed
● package 256MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mpf
✓ import mplfinance as mpf
This quickstart generates dummy OHLCV data using Pandas and NumPy, then plots a basic candlestick chart with volume using `mpf.plot()`. It demonstrates the required DataFrame format (DatetimeIndex, specific column names) and common plotting parameters like `type`, `style`, and `volume`. The `returnfig=True` argument allows access to the underlying Matplotlib Figure and Axes objects for further customization or saving.
import mplfinance as mpf
import pandas as pd
import numpy as np
# Create dummy OHLCV data with DatetimeIndex
dates = pd.date_range('2023-01-01', periods=50, freq='D')
np.random.seed(42)
open_price = np.random.rand(50) * 100 + 100
close_price = open_price + np.random.randn(50) * 5
high_price = np.maximum(open_price, close_price) + np.random.rand(50) * 2
low_price = np.minimum(open_price, close_price) - np.random.rand(50) * 2
volume = np.random.rand(50) * 1000000
df = pd.DataFrame({
'Open': open_price,
'High': high_price,
'Low': low_price,
'Close': close_price,
'Volume': volume
}, index=dates)
# Plot a basic candlestick chart with volume
fig, axes = mpf.plot(df,
type='candle',
style='yahoo',
volume=True,
title='Sample Candlestick Chart',
ylabel='Price',
ylabel_lower='Volume',
returnfig=True
)
# To display the plot in a non-interactive environment or save it
# fig.savefig('candlestick_chart.png')
# import matplotlib.pyplot as plt
# plt.show() # Uncomment for interactive display
Debug
Known issues
gotchamplfinance expects input data as a Pandas DataFrame with a DatetimeIndex and specific column names (case-sensitive): 'Open', 'High', 'Low', 'Close', and optionally 'Volume'. Incorrect indexing or column naming will lead to errors.fixEnsure your DataFrame's index is `pd.DatetimeIndex` and column names are exactly 'Open', 'High', 'Low', 'Close', 'Volume'. Use `df.rename()` or `df.columns = [...]` if necessary.
affects: All versions
deprecatedOlder versions of mplfinance (prior to 0.12.9b7) may issue deprecation warnings or encounter compatibility issues when run with recent versions of Matplotlib or Pandas.fixUpgrade mplfinance to version 0.12.9b7 or newer to benefit from fixes addressing deprecation warnings and improved compatibility with modern Matplotlib/Pandas releases. Also ensure Matplotlib and Pandas are up-to-date.
affects: < 0.12.9b7
gotchaDirect manipulation of Matplotlib Axes objects returned by `mpf.plot()` can be challenging due to mplfinance's internal panel structure. For overlaying custom data series or indicators, the `addplot` kwarg is the idiomatic approach.fixUse `mpf.make_addplot()` to create 'addplot' objects for overlay data (e.g., scatter plots, lines), then pass a list of these objects to the `addplot` keyword argument of `mpf.plot()`. For general chart customization, explore `mpf.plot()`'s extensive keyword arguments (e.g., `style`, `marketcolors`).
affects: All versions
gotchamplfinance frequently releases beta versions (e.g., `0.12.10b0`) which may introduce minor API changes or new features that are refined rapidly. While generally stable, users should monitor release notes carefully.fixWhen using pre-release versions, review the GitHub changelog for each update. For production environments requiring strict stability, consider pinning to exact minor versions.
affects: All pre-release (`b`) versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mplfinance'
The `mplfinance` library is not installed in the Python environment being used, or there is a conflict with an old, deprecated `mpl_finance` installation.
fixEnsure `mplfinance` is installed by running `pip install --upgrade mplfinance`. If using a virtual environment or Jupyter, confirm it's installed in the correct environment.
KeyError: 'Open'
`mplfinance` expects the input Pandas DataFrame to have specific column names: 'Open', 'High', 'Low', 'Close', and optionally 'Volume' (case-sensitive). This error occurs when one or more of these expected columns are missing or incorrectly named.
fixRename your DataFrame columns to match the expected 'Open', 'High', 'Low', 'Close', and 'Volume' (with correct capitalization) before passing it to `mpf.plot()`. Ensure the index is a DatetimeIndex.
ValueError: Data must be a DataFrame with a DateTimeIndex
`mplfinance` requires the input data to be a Pandas DataFrame where the index is of `DatetimeIndex` type, which is crucial for time-series plotting.
fixConvert the DataFrame's index to a `DatetimeIndex` using `pd.to_datetime()` and `df.set_index()` if your date/time column is not already the index or is not in datetime format.
mplfinance error，Data for column "Open" must be ALL float or int
The data within the 'Open', 'High', 'Low', 'Close', or 'Volume' columns of the DataFrame contains non-numeric values (e.g., strings), while `mplfinance` expects these financial data points to be entirely of float or integer type.
fixInspect the data types of your OHLCV columns using `df.dtypes`. Convert any non-numeric data in these columns to float or int using `pd.to_numeric(df['Column'], errors='coerce')` to handle potential non-convertible values gracefully.
ValueError: x and y must be the same size
This error typically occurs when using `mpf.make_addplot()` to add overlay plots (e.g., scatter plots for signals or additional lines) where the data array for the overlay does not have the same number of elements as the main OHLCV data being plotted.
fixEnsure that any data passed to `mpf.make_addplot()` (especially for scatter plots or lines) has the exact same length and DateTimeIndex as the main DataFrame passed to `mpf.plot()`. Often, this means creating a Series filled with `np.nan` for non-signal points and only populating the signal points.
Upgrade
Version history
0.12.10b0latest on PyPI · released Aug 2, 2023
Audit
Dependencies
matplotlibrequiredCore plotting library, mplfinance is built on top of it.
pandasrequiredRequired for data handling, especially DataFrames and DatetimeIndex.