# How to Run FastAPI from PyCharm: Essential Setup Steps

> Learn to run FastAPI from PyCharm. Install FastAPI, create a main.py file, and configure a Python Run/Debug setup to easily get your server running inside the IDE.

- Repository: [Sebastián Ramírez/fastapi](https://github.com/tiangolo/fastapi)
- Tags: getting-started
- Published: 2026-02-16

---

**To run FastAPI from PyCharm, install FastAPI with the `[standard]` extras, create a [`main.py`](https://github.com/tiangolo/fastapi/blob/main/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:

```bash
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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/docs/en/docs/virtual-environments.md).

### Create the FastAPI Application File

Create a file named [`main.py`](https://github.com/tiangolo/fastapi/blob/main/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:

```python
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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/fastapi/__main__.py), which parses your [`main.py`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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:

```text
 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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/main.py) so the FastAPI CLI can discover it according to the pattern in [`docs_src/settings/app01_py310/main.py`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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`](https://github.com/tiangolo/fastapi/blob/main/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`.