如何在Matplotlib FuncAnimation中更新外部Pandas DataFrame且不设为全局变量

报错核心原因 #

这个UnboundLocalError和Matplotlib动画逻辑无关，本质是Python的变量作用域判定规则导致的：

• 只要在函数内部存在对某变量的赋值操作，Python就会默认把该变量判定为函数的局部变量，不会自动向外查找外层作用域的同名变量。
• 触发报错的代码里写了df = df.append(new_row, ignore_index=True)，这行代码本身就触发了上述规则，Python会认为df是animate的局部变量，当执行到赋值语句右侧、需要读取df值做append操作时，局部作用域的df还未完成初始化赋值，就会抛出报错。
• 对比你原来的列表实现：原代码里是xs.append(i)，属于对列表对象的原地方法调用，没有给xs变量本身重新赋值，因此Python不会把xs判定为局部变量，可以正常读取外层定义的列表对象，自然不会触发报错。

无需全局变量的可行实现方案 #

所有方案的核心都是绕开“在animate函数内部直接对外层df变量赋值”的行为，从作用域判定层面规避报错：

方案1：用可变容器封装DataFrame #

将DataFrame存入字典、列表等可变容器中，在函数内修改容器内容而非给外层变量赋值：

import matplotlib.animation as animation
import matplotlib.pyplot as plt
import pandas as pd

fig, ax = plt.subplots()
# 用字典作为可变容器存放初始DataFrame
data_store = {
    "df": pd.DataFrame(columns=['x', 'y'])
}

def animate(i):
    new_row = pd.DataFrame([{'x': i, 'y': i**2}])
    # 修改字典内的元素，不对外层的data_store变量本身赋值
    data_store["df"] = pd.concat([data_store["df"], new_row], ignore_index=True)
    ax.clear()
    ax.plot(data_store["df"]['x'], data_store["df"]['y'])

ani = animation.FuncAnimation(fig, animate, interval=1000)
plt.show()

方案2：用类封装动画全量状态 #

将DataFrame、画布、轴对象都作为类实例的属性管理，回调函数绑定为类的方法，全程无全局变量：

class SimpleLineAnimation:
    def __init__(self):
        self.fig, self.ax = plt.subplots()
        self.line_data = pd.DataFrame(columns=['x', 'y'])
        # 初始化动画实例
        self.ani = animation.FuncAnimation(
            self.fig, self.update_frame, interval=1000
        )

    def update_frame(self, i):
        new_row = pd.DataFrame([{'x': i, 'y': i**2}])
        self.line_data = pd.concat([self.line_data, new_row], ignore_index=True)
        self.ax.clear()
        self.ax.plot(self.line_data['x'], self.line_data['y'])

anim = SimpleLineAnimation()
plt.show()

方案3：通过FuncAnimation的fargs参数传入状态 #

利用FuncAnimation内置的fargs参数，将封装好的状态容器作为参数传递给回调函数，避免直接在函数内引用外层变量：

fig, ax = plt.subplots()
# 用列表作为可变容器存放DataFrame
df_container = [pd.DataFrame(columns=['x', 'y'])]

def animate(i, data_wrapper):
    new_row = pd.DataFrame([{'x': i, 'y': i**2}])
    data_wrapper[0] = pd.concat([data_wrapper[0], new_row], ignore_index=True)
    ax.clear()
    ax.plot(data_wrapper[0]['x'], data_wrapper[0]['y'])

ani = animation.FuncAnimation(
    fig, animate, interval=1000, fargs=(df_container,)
)
plt.show()

额外注意事项 #

• 原代码中使用的DataFrame.append方法已在pandas新版本中标记为弃用，推荐使用pd.concat做行拼接，兼容性更好。
• 每帧更新前记得调用ax.clear()清空轴内容，避免多帧折线叠加绘制，和原列表实现的表现保持一致。
• 不推荐直接通过global df声明全局变量来解决问题，全局作用域的状态会大幅提升代码后续维护的复杂度，容易出现状态污染问题。

内容的提问来源于stack exchange，提问作者Pedantic