Running uvicorn from subfolder results in ModuleNotFoundError

What You Will Learn

In this tutorial, you will learn how to successfully run uvicorn from a subfolder without encountering a ModuleNotFoundError. We will explore the common issue that arises when attempting to execute uvicorn from a subdirectory within a Python project and provide practical solutions to overcome it.

Introduction to the Problem and Solution

When running uvicorn from a subfolder in a Python project, you may face a ModuleNotFoundError due to the inability of uvicorn to locate the required modules in a different directory. To tackle this issue effectively, we need to adjust our approach by specifying the correct path or utilizing alternative methods.

To resolve the ModuleNotFoundError when running uvicorn from a subfolder, we can modify our command by using Python’s -m flag. This flag allows us to run modules as scripts directly, ensuring that uvicorn can find all necessary modules regardless of the current working directory.


# To run uvicorn from a subfolder using -m flag
python -m <subfolder>.<script_name>

# Copyright PHD

Replace <subfolder> with your actual subfolder name and <script_name> with your script file name. For example:

python -m my_subfolder.my_script 

# Copyright PHD

For more detailed explanations and examples related to Python concepts and issues, visit PythonHelpDesk.com.


When executing uvicorn from a subdirectory, it is crucial to address module import errors by utilizing the -m flag. By specifying both the subdirectory and script name after -m, we provide Python with the necessary information for successful execution, ensuring that all modules are found correctly.

    1. How does running uvicorn with -m flag differ from regular execution? Running uvicorn with -m bypasses potential import errors related to module discovery since it directly runs specified scripts.

    2. Can I specify additional arguments when using -m with uvicorn? Yes, you can include additional arguments after specifying the module name following -m.

    3. What if my script requires access to files in another directory? Ensure correct definition of relative paths within your script for accessing files outside its immediate directory structure.

    4. Is there an alternative solution if using -m is not feasible for my workflow? Adjust system environmental variables or modify sys.path programmatically within your code for resolving module dependencies.

    5. Why does changing directories before executing uvicorn not resolve this issue? Changing directories only affects command execution locations but doesn’t impact how Python resolves imports unless accompanied by additional modifications like adjusting sys.path.


Resolving ModuleNotFoundError when running uvicron from subfolders involves understanding how Python locates modules based on execution contexts. By leveraging python’s command-line options like – m, we ensure seamless execution irrespective of our current working directory.

Leave a Comment