{"id":6506,"library":"aioshutil","title":"aioshutil: Asynchronous shutil module","description":"aioshutil is a Python library that provides asynchronous versions of functions from the standard `shutil` module. It achieves asynchronicity by running blocking I/O operations in a thread pool, thereby preventing the blocking of the asyncio event loop. The library is actively maintained, with the current version being 1.6.","status":"active","version":"1.6","language":"en","source_language":"en","source_url":"https://github.com/kumaraditya303/aioshutil","tags":["asyncio","shutil","io","asynchronous","file-operations"],"install":[{"cmd":"pip install aioshutil","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"copy","correct":"from aioshutil import copy"},{"symbol":"rmtree","correct":"from aioshutil import rmtree"},{"symbol":"move","correct":"from aioshutil import move"}],"quickstart":{"code":"import asyncio\nimport aioshutil\nimport os\n\nasync def main():\n    # Ensure a directory exists for demonstration\n    if not os.path.exists('test_dir_src'):\n        os.makedirs('test_dir_src')\n    with open('test_dir_src/test_file.txt', 'w') as f:\n        f.write('Hello, aioshutil!')\n\n    print('Copying file asynchronously...')\n    await aioshutil.copy('test_dir_src/test_file.txt', 'test_dir_dest_copy.txt')\n    print('File copied.')\n\n    print('Moving file asynchronously...')\n    await aioshutil.move('test_dir_src/test_file.txt', 'test_dir_dest_move.txt')\n    print('File moved.')\n\n    print('Removing directory asynchronously...')\n    await aioshutil.rmtree('test_dir_src')\n    print('Directory removed.')\n\n    # Clean up created files/dirs if they exist from previous runs/failures\n    if os.path.exists('test_dir_dest_copy.txt'):\n        os.remove('test_dir_dest_copy.txt')\n    if os.path.exists('test_dir_dest_move.txt'):\n        os.remove('test_dir_dest_move.txt')\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to use `aioshutil` to perform common file operations like copying, moving, and removing directories asynchronously within an `asyncio` application. It mirrors the `shutil` API but with `await` calls."},"warnings":[{"fix":"Understand that 'asynchronous' in this context means non-blocking to the Python event loop, not necessarily non-blocking kernel I/O. Benchmark if extreme low-level I/O latency is critical.","message":"aioshutil performs its asynchronous operations by offloading blocking `shutil` calls to a thread pool (`loop.run_in_executor()`). This prevents blocking the asyncio event loop, but the underlying file operations are still blocking at the OS level. Users expecting true non-blocking I/O at a lower system level should be aware of this implementation detail.","severity":"gotcha","affected_versions":"All"},{"fix":"Initialize `asyncio` primitives within an `async` function (e.g., inside `main()` or as part of an `__init__` method for async classes) after the event loop has been established by `asyncio.run()`. Python 3.10 and later mitigate this specific issue for `asyncio.Lock` by removing the `loop` parameter.","message":"When using `asyncio` objects (like `asyncio.Lock` or similar constructs) globally or outside of an `async` function before `asyncio.run()` is called, they might capture a stale reference to an implicit event loop. When `asyncio.run()` is invoked, it creates a new event loop, leading to potential runtime errors or unexpected behavior with the previously initialized objects. While primarily an `asyncio` footgun, it's relevant for any library interacting with the event loop like `aioshutil`.","severity":"gotcha","affected_versions":"<3.10"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install aioshutil'.","cause":"The 'aioshutil' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'aioshutil'"},{"fix":"Ensure you are using the correct function names as provided by 'aioshutil'.","cause":"The function 'rmtree' is not available in the 'aioshutil' module.","error":"ImportError: cannot import name 'rmtree' from 'aioshutil'"},{"fix":"Use 'await' when calling asynchronous functions: 'await aioshutil.rmtree(path)'.","cause":"Attempting to call an asynchronous function from 'aioshutil' without using 'await'.","error":"TypeError: 'coroutine' object is not callable"},{"fix":"Verify the available functions in 'aioshutil' and use the correct ones.","cause":"The function 'copytree' is not available in the 'aioshutil' module.","error":"AttributeError: module 'aioshutil' has no attribute 'copytree'"},{"fix":"Use 'nest_asyncio' to allow nested use of 'asyncio' in environments like Jupyter Notebook.","cause":"Calling 'aioshutil' functions within an already running event loop, such as in Jupyter Notebook.","error":"RuntimeError: This event loop is already running"}]}