如何在可同时作为Jupyter Notebook运行的Python脚本中使用asyncio？

阿华AIGC实验室

2026-4-27

解决Jupyter与脚本模式下的异步代码兼容问题

我之前也碰到过完全一样的麻烦——用带# %%分隔符的.py文件兼顾Jupyter交互式运行和普通脚本模式时，异步代码总是两边“水土不服”。试过nest-asyncio踩了兼容性坑，调autoawait也没解决问题，后来摸索出两个靠谱的方案，分享给你：

方案1：主动检测运行环境

通过判断当前是否处于Jupyter环境，分支执行对应的异步调用逻辑：

# %%
import asyncio

def is_running_in_jupyter():
    try:
        from IPython import get_ipython
        # 检查是否存在IPython实例，且是Jupyter内核环境
        return get_ipython() is not None and 'IPKernelApp' in get_ipython().config
    except ImportError:
        # 没装IPython肯定不是Jupyter环境
        return False

async def my_async_func():
    await asyncio.sleep(1)
    return "搞定异步兼容！"

# %%
if is_running_in_jupyter():
    # Jupyter环境下直接用顶层await（依赖默认开启的autoawait）
    result = await my_async_func()
else:
    # 普通脚本环境用asyncio.run启动事件循环
    result = asyncio.run(my_async_func())

print(result)

这个方案逻辑清晰，通过IPython的配置明确判断环境，不需要依赖异常捕获来做分支处理。

方案2：被动捕获异常兼容

如果不想引入IPython的依赖，可以直接通过asyncio.run()的异常来判断当前是否已有运行中的事件循环：

# %%
import asyncio

async def my_async_func():
    await asyncio.sleep(1)
    return "搞定异步兼容！"

# %%
try:
    # 先尝试用脚本模式的方式运行
    result = asyncio.run(my_async_func())
except RuntimeError as e:
    # 如果报错是"无法从运行中的事件循环调用"，说明是Jupyter环境
    if "cannot be called from a running event loop" in str(e):
        result = await my_async_func()
    else:
        # 其他异常正常抛出，不吞错误
        raise

print(result)

这个方案更通用，哪怕是在IPython终端这类支持顶层await的环境也能正常工作，不需要额外导入库。