How to Run FastAPI from PyCharm: Essential Setup Steps

To run FastAPI from PyCharm, install FastAPI with the [standard] extras, create a main.py file exposing a FastAPI instance named app, and configure a Python Run/Debug configuration that executes fastapi dev main.py using your project's virtual environment interpreter.

Setting up FastAPI within an integrated development environment streamlines the development workflow for building high-performance APIs. This guide walks through the exact steps to run FastAPI from PyCharm using the official CLI tools provided in the tiangolo/fastapi repository. By following these instructions, you will configure a virtual environment, set up the necessary run configuration, and launch a development server with auto-reload capabilities directly within the IDE.

Steps to Run FastAPI from PyCharm

Install FastAPI and Configure the Virtual Environment

Begin by creating an isolated Python environment to manage dependencies. Execute the following commands in your terminal:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install "fastapi[standard]"

The [standard] extras bundle includes Uvicorn, the ASGI server that powers FastAPI, along with the FastAPI CLI entry point defined in fastapi/__main__.py. This installation method ensures all components required to run FastAPI from PyCharm are available in your virtual environment, as documented in docs/en/docs/virtual-environments.md.

Create the FastAPI Application File

Create a file named main.py in your project root that exposes a FastAPI instance as the variable app. This naming convention is required for the CLI to locate your application object:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI from PyCharm!"}

This pattern matches the structure used throughout the FastAPI documentation examples, such as those found in docs_src/settings/app01_py310/main.py. The app variable serves as the import target for the FastAPI CLI when it processes the dev main.py command.

Configure the Python Interpreter in PyCharm

Direct PyCharm to use the virtual environment's Python interpreter to ensure dependency resolution. Navigate to Settings → Project → Python Interpreter, click the gear icon, and select Add → Existing Environment. Point to the Python binary inside your .venv directory (.venv/bin/python on macOS/Linux or .venv\Scripts\python.exe on Windows).

This configuration step is crucial because it allows PyCharm to recognize the fastapi command and associated packages installed in the isolated environment, ensuring the runtime matches the command-line experience.

Set Up the Run/Debug Configuration

Create a run configuration that invokes the FastAPI CLI with the development server. Go to Run → Edit Configurations, click the plus icon, and select Python. Configure the following fields:

• Script path: fastapi (or the full path to .venv/bin/fastapi or .venv\Scripts\fastapi.exe)
• Parameters: dev main.py
• Working directory: Your project root directory
• Python interpreter: The virtual environment interpreter configured in the previous step

The fastapi script calls fastapi/__main__.py, which parses your main.py file, locates the app object, and launches Uvicorn with development-friendly settings. The fastapi dev command is documented in docs/en/docs/fastapi-cli.md and enables auto-reload by default.

Launch the Server and Verify

Execute the configuration by clicking the Run button or pressing Shift+F10. PyCharm's console will display output similar to:

 FastAPI  Starting development server 🚀
 Searching for package file structure from directories with __init__.py files
 Importing from /path/to/your/project
 module  🐍 main.py
 code    Importing the FastAPI app object from the module with
          from main import app
 app     Using import string: main:app
 server  Server started at http://127.0.0.1:8000
 server  Documentation at http://127.0.0.1:8000/docs
 INFO    Will watch for changes in these directories: ['/path/to/your/project']
 INFO    Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Your API is now accessible at http://127.0.0.1:8000 with interactive documentation available at http://127.0.0.1:8000/docs. The server will automatically restart when you modify your code, as implemented in the CLI logic within fastapi/__main__.py.

Understanding the FastAPI CLI Entry Point

When you run the fastapi dev command from PyCharm, you are executing the entry point defined in fastapi/__main__.py. This module implements the FastAPI CLI, which performs several critical operations:

• Module Discovery: It searches for Python files containing a FastAPI instance named app
• ASGI Server Initialization: It launches Uvicorn with the detected application import string (e.g., main:app)
• Development Mode: The dev subcommand automatically enables auto-reload, watching your project directory for file changes and restarting the server without manual intervention

This architecture allows PyCharm to manage the process lifecycle while FastAPI handles the server execution, providing a seamless development experience identical to command-line usage.

Summary

• Install FastAPI with the [standard] extras to bundle Uvicorn and the CLI tools required for PyCharm integration
• Expose your application as an app variable in main.py so the FastAPI CLI can discover it according to the pattern in docs_src/settings/app01_py310/main.py
• Configure the virtual environment interpreter in PyCharm settings to resolve dependencies correctly
• Create a Run configuration using fastapi dev main.py as the execution target to enable development features
• Leverage auto-reload built into the fastapi dev command for immediate feedback during development

Frequently Asked Questions

How do I enable auto-reload when running FastAPI from PyCharm?

Auto-reload is enabled by default when using the fastapi dev command in your PyCharm run configuration. The CLI, implemented in fastapi/__main__.py, automatically monitors your project directories for changes and restarts the Uvicorn server without requiring a manual stop and restart. No additional configuration is needed beyond using the dev subcommand as documented in docs/en/docs/fastapi-cli.md.

What Python interpreter should I select for FastAPI in PyCharm?

Select the interpreter from your project's virtual environment (.venv/bin/python or .venv\Scripts\python.exe). This ensures PyCharm uses the specific Python installation where you executed pip install "fastapi[standard]", guaranteeing access to the fastapi CLI and all dependencies. The virtual environments documentation at docs/en/docs/virtual-environments.md provides detailed guidance on this configuration.

Can I debug FastAPI endpoints using PyCharm's debugger?

Yes. Instead of using the standard Run action, use the Debug action (or press Shift+F9) with the same run configuration. Set breakpoints in your main.py file or imported modules, and PyCharm will pause execution at those lines while processing incoming HTTP requests. The debugger works seamlessly with the fastapi dev command, allowing you to inspect variables and step through endpoint logic.

Why does PyCharm fail to find the fastapi command?

This typically occurs when the project interpreter is not set to the virtual environment where FastAPI is installed. Verify that Settings → Project → Python Interpreter points to the .venv directory created earlier. If the interpreter is correct but the issue persists, specify the full path to the fastapi executable in the run configuration's script path field, usually located at .venv/bin/fastapi or .venv/Scripts/fastapi.exe.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}