asyncio.run() cannot be called from a running event loop 오류는 같은 스레드에서 이벤트 루프가 이미 실행 중일 때 asyncio.run()을 호출하면 발생합니다. 현재 사용 중인 Python과 실행 환경에서, 같은 스레드에 실행 중인 루프가 없는 일반 .py 파일의 동기 진입점이라면 asyncio.run(main())을 사용할 수 있습니다. Jupyter·Colab 셀이 최상위 await를 지원한다면 이를 사용하고, 실행 중인 비동기 함수에서는 목적에 따라 await 또는 create_task()를 선택합니다. 먼저 asyncio.get_running_loop()으로 현재 스레드에 실행 중인 루프가 있는지 확인하면, 오류를 억지로 감추지 않고 호출 방식을 결정할 수 있습니다.
이 문제는 asyncio 자체가 고장 난 것이 아니라 이벤트 루프의 소유권이 겹친 상황입니다. 코드를 다른 실행 환경으로 옮길 때는 호출 위치를 먼저 구분하는 습관이 중요합니다.
asyncio.run()이 실패하는 이유
Python 공식 문서에서 asyncio.run()은 코루틴을 실행하기 위한 최상위 진입점입니다. 이 함수는 새 이벤트 루프를 만들고 코루틴을 실행한 뒤 루프를 닫습니다. 따라서 같은 스레드에서 이벤트 루프가 이미 실행 중이면 asyncio.run()을 호출할 수 없습니다.
import asyncio
async def main():
print("비동기 작업")
if __name__ == "__main__":
asyncio.run(main())
이 예제처럼 프로그램의 동기 최상위 진입점에서 한 번 시작하는 방식은 일반 스크립트에 알맞습니다. 반대로 이미 async def 안에 있다면 그 함수가 이벤트 루프의 관리 아래에 있으므로 asyncio.run()을 다시 부를 이유가 없습니다.
먼저 실행 중인 이벤트 루프를 확인하기
현재 코드가 코루틴이나 콜백 안에서 실행된다면 asyncio.get_running_loop()을 진단에 사용할 수 있습니다. 실행 중인 루프가 있으면 루프 객체를 반환하고, 없으면 RuntimeError가 발생합니다.
import asyncio
def check_running_loop():
try:
loop = asyncio.get_running_loop()
except RuntimeError:
return "현재 실행 중인 이벤트 루프가 없습니다."
return f"이벤트 루프가 실행 중입니다: {loop!r}"
이 함수는 상태를 확인할 뿐 비동기 작업을 대신 실행하지는 않습니다. 루프가 있다는 사실을 확인한 다음, 호출 위치에 맞는 진입 방식을 선택해야 합니다.
실행 환경별로 어떤 방법을 선택할까
일반 .py 파일의 최상위 동기 코드
터미널에서 독립적으로 실행하는 일반 Python 파일이라면 동기 최상위 코드에서 asyncio.run(main())으로 비동기 프로그램을 시작하는 구성이 기본입니다.
import asyncio
async def fetch_data():
return "완료"
async def main():
result = await fetch_data()
print(result)
if __name__ == "__main__":
asyncio.run(main())
여기서 핵심은 main()이 코루틴이라는 점과 asyncio.run()이 그 코루틴을 실행할 최상위 경계라는 점입니다. 같은 이벤트 루프에서 최상위 비동기 함수를 여러 번 실행해야 한다면 asyncio.Runner를 검토할 수 있지만, Runner.run()도 같은 스레드에 실행 중인 이벤트 루프가 있으면 호출할 수 없습니다. asyncio.Runner는 Python 3.11부터 제공됩니다.
Jupyter·Colab 셀
Jupyter나 Colab 셀에서 이 오류가 발생했다면 현재 스레드의 루프 상태를 먼저 확인하십시오. 해당 환경이 최상위 await를 지원한다면 셀에서 코루틴을 직접 기다리는 방식을 선택할 수 있습니다.
await main()
최상위 await의 지원 여부는 사용 중인 환경에서 확인하십시오. 오류 메시지와 get_running_loop()의 결과를 함께 확인하는 편이 안전합니다. 실행 중인 루프 안에 새 루프를 겹쳐 넣는 방식이나 nest_asyncio를 만능 해결책처럼 적용하기보다, 해당 환경이 제공하는 await 경계를 우선 살펴보십시오.
이미 async def인 함수나 비동기 콜백
호출하는 쪽이 이미 비동기 함수라면 새 실행기를 만들지 말고 await로 작업을 이어 갑니다.
async def callback():
result = await fetch_data()
return result
동시에 시작할 작업을 예약하고 현재 함수가 다른 일을 계속해야 한다면 asyncio.create_task()를 사용할 수 있습니다.
import asyncio
async def callback():
task = asyncio.create_task(fetch_data())
result = await task
return result
create_task()는 현재 실행 중인 이벤트 루프를 사용해 코루틴 실행을 예약하고 Task를 반환합니다. 따라서 실행 중인 루프가 없는 동기 코드에서 바로 호출하는 방식은 적합하지 않습니다. Task를 만들었다면 결과와 예외를 실제로 기다려 확인해야 하며, 단순히 예약만 하고 함수가 끝나면 작업의 생명주기를 놓칠 수 있습니다.
동기 함수에서 비동기 코루틴을 호출해야 하는 경우
동기 함수가 실행 중인 이벤트 루프에 코루틴을 제출해야 한다면, 그 루프와 다른 OS 스레드에서 asyncio.run_coroutine_threadsafe()를 호출하도록 설계할 수 있습니다. 이 방법은 일반적인 asyncio.run() 대체 구문이 아니라, 실행 중인 특정 루프에 스레드 안전하게 코루틴을 제출해야 하는 상황을 위한 경계입니다.
import asyncio
def submit_from_worker(loop, coroutine):
future = asyncio.run_coroutine_threadsafe(coroutine, loop)
return future
이 패턴을 선택하려면 대상 루프가 실제로 실행 중인지, 결과와 예외를 어떤 방식으로 회수할지, 스레드 종료를 어떻게 관리할지까지 함께 정해야 합니다. 단순히 오류 메시지를 없애려는 목적으로 스레드를 추가하면 구조가 더 복잡해질 수 있습니다.
선택 순서를 짧게 정리하면
호출 위치를 먼저 확인한 뒤 다음 순서로 판단하면 됩니다.
- 일반
.py파일의 동기 최상위 진입점인가요? 그렇다면asyncio.run(main())을 사용합니다. - 이미
async def또는 비동기 콜백 안인가요?await로 코루틴을 실행하고, 동시 작업을 예약할 때만create_task()를 검토합니다. - Jupyter·Colab 셀에서 실행 중인 루프가 있나요? 지원되는 최상위
await를 우선 사용하고 런타임 차이를 확인합니다. - 동기 코드가 다른 스레드에서 실행 중인 루프에 제출해야 하나요? 그때만
run_coroutine_threadsafe()를 검토합니다.
이렇게 구분하면 asyncio.run()을 어디서나 반복 호출하는 문제와, 반대로 모든 오류를 외부 패키지로 덮는 문제를 함께 피할 수 있습니다.
마무리: 오류보다 호출 경계를 먼저 보십시오
asyncio.run() 오류의 핵심은 비동기 작업의 내용보다 현재 코드가 이벤트 루프의 안쪽인지 바깥쪽인지에 있습니다. get_running_loop()으로 상태를 확인하고, 바깥의 동기 진입점에서는 asyncio.run(), 안쪽의 비동기 문맥에서는 await나 create_task()를 선택하는 것이 기본 원칙입니다.
코드를 여러 실행 환경에 배포할 예정이라면 함수 자체와 실행 진입점을 분리해 두는 것이 좋습니다. 비동기 로직은 async def로 두고, 일반 스크립트·노트북·서비스 콜백이 각자의 방식으로 그 로직을 호출하게 하면 환경이 바뀌어도 이벤트 루프 충돌을 좁은 경계에서 다룰 수 있습니다.