How to solve uv not working in PyCharm?

Apr 3, 2025

1. Purpose

In this post, I will demonstrate how to solve the following error when using uv to install packages in PyCharm:

First, I used the pyenv and uv tool to initialize a python project

#use pyenv to set python local version
pyenv local 3.12

Verify the python version:

➜  python --version
Python 3.12.9

It’s correct.

Then create project:

# Create project
uv init fastapi_sse --bare

# Change to project directory
cd fastapi_sse

# Install FastAPI
uv add fastapi --extra standard

# Install MCP
uv add mcp

# Create fastapi app
mkdir app
touch app/__init__.py
touch app/main.py

Then fill the main.py with such content:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}

Verify that uv has successfully installed the fastapi package:

➜  uv pip list|grep fastapi
fastapi           0.115.12
fastapi-cli       0.0.7
➜

You can see the fastapi package is correctly installed. Everything works fine now.

but in pycharm , I got this: It seems that pycharm does not recognize the fastapi package, but I have already installed it!

Why did this happen？

2. The Solution

2.1 What is uv?

uv is an extremely fast Python package installer and resolver, written in Rust, and designed as a drop-in replacement for pip and pip-tools workflows.

Here is a comparsion between uv and pip: It shows that uv is very fast.

2.2 Debug1: Check pycharm python interpreter

Let’s check the pycharm’s python interpreter: It’s correct.

2.3 Debug2: Check how pycharm find packages

So I ask AI how pycharm find packages, I got this:

PyCharm has the following methods to locate packages:

### 1. Virtual Environments
- **Creation and Association**: When you create a new project in PyCharm, you have the option to set up a virtual environment. You can create a virtual environment based on Python's built - in `venv` module or use `conda` environments. After creation, PyCharm will associate the project with this virtual environment.
- **Package Search**: Once associated, PyCharm will search for packages installed within this virtual environment. For example, if you use the PyCharm's built - in terminal to run `pip install requests` in the virtual environment, PyCharm will recognize the `requests` package and make it available for import in your project.

### 2. System - Wide Python Interpreter
- **Configuration**: If you choose to use the system - wide Python interpreter for your project, PyCharm will search for packages installed in the directories associated with that interpreter. For instance, on a Linux system, the default Python packages are usually installed in `/usr/local/lib/pythonX.Y/site - packages` (where `X.Y` is the Python version).
- **Detection**: PyCharm will detect packages installed via system - wide package managers like `pip` or `apt` (in the case of Python packages installed along with other system packages).

### 3. Package Repositories
- **PyPI**: PyCharm can directly interact with the Python Package Index (PyPI). When you try to install a package using PyCharm's "Project Interpreter" settings, it will query PyPI to find the package and its available versions.
- **Custom Repositories**: You can also configure PyCharm to use custom package repositories. In the "Project Interpreter" settings, you can add the URL of a custom repository, and PyCharm will search for packages there when needed.

### 4. Caching and Indexing
- **Indexing Process**: PyCharm builds an index of all the packages and their contents in the project's interpreter. This index helps in quickly locating packages and their functions, classes, etc. You can trigger a manual re - indexing if needed from the "File" -> "Invalidate Caches / Restart" menu.
- **Caching**: It caches information about installed packages to speed up subsequent searches. If you install a new package, the cache may need to be updated for PyCharm to immediately recognize it.

So I think the problem is :

I used uv add to install packages
Those uv packages not recognized by pycharm

So where did uv put my packages ?

2.4 Debug3：Where did uv put the installed packages?

I ask AI again:

      Me: I use `uv add`, where does the packages installed?

AI:
When you use `uv add`, the packages are installed into a virtual environment managed by uv. The precise location of this virtual environment depends on how you've set up uv and whether you're working within an existing project or creating a new one.

Here's a breakdown:

- **Within a Project:**
    - If you're in a directory containing a `pyproject.toml` file (or a `requirements.txt` file, if you've configured uv to use it), uv will typically create or use a virtual environment within that project directory.
    - The default location for this virtual environment is often a `.venv` directory in the project's root. So the packages are installed inside that `.venv` directory.
    - uv is designed to work well with the PEP 582 standard, so it can also install packages into a `__pypackages__`directory.
- **Outside a Project:**
    - If you run `uv add` outside of a project directory, uv may create a global virtual environment or behave in a way that depends on your configuration.
    - uv also has a cache directory. 1 Where it stores downloaded packages.

        [1. Caching | uv - Astral Docs](https://docs.astral.sh/uv/concepts/cache/#:~:text=UV_CACHE_DIR%20%2C%20or%20tool.-,uv.,%25%5Cuv%5Ccache%20on%20Windows)

        [

        ![Source icon](https://encrypted-tbn0.gstatic.com/favicon-tbn?q=tbn:ANd9GcSjnScyy_9aAQ4v7GDPR2vSYJmSD9c0T54JumB_2M4AcnExVEsphqfXDDwne6TaIR017Ybxw0tpdniREQDKQ0FeNFDWj7uILv4)

        docs.astral.sh

        ](https://docs.astral.sh/uv/concepts/cache/#:~:text=UV_CACHE_DIR%20%2C%20or%20tool.-,uv.,%25%5Cuv%5Ccache%20on%20Windows)

    - The exact behaviour is still evolving, as uv is a relatively new tool.

In essence, `uv add` places packages within a virtual environment so that they are isolated from your system's global Python installation. The most common location for this virtual environment, when inside a project, is the `.venv` directory.

So, I checked the uv ‘.venv’ directory, I found the fastapi:

So ,uv correctly installed the fastapi dependency, but it can not be found by pycharm, I need to find it out.

I Ask AI again, it replied:

This is a common issue when using virtual environments with PyCharm, and it typically boils down to PyCharm not being configured to use the correct virtual environment. Here's a breakdown of the possible causes and how to fix them:

**1. PyCharm's Project Interpreter is Incorrect:**

- **The Problem:** PyCharm might be using a different Python interpreter (e.g., your system's Python or a different virtual environment) instead of the `.venv` you created with uv.
- **The Solution:**
    - Open PyCharm's settings (File > Settings or PyCharm > Preferences on macOS).
    - Navigate to Project: [Your Project Name] > Python Interpreter.
    - Click the gear icon next to the "Python Interpreter" dropdown and select "Add Interpreter."
    - Choose "Existing environment."
    - Browse to the `.venv/bin/python` (or `.venv/Scripts/python.exe` on Windows) executable within your project directory.
    - Click "OK" and ensure that the correct `.venv` interpreter is now selected.

**2. PyCharm's Indexing Issues:**

- **The Problem:** PyCharm might not have properly indexed the packages in your `.venv` directory.
- **The Solution:**
    - Invalidate PyCharm's caches and restart it (File > Invalidate Caches / Restart). This forces PyCharm to re-index your project and its dependencies.

**3. PyCharm's Content Roots:**

- **The Problem:** In rare cases, PyCharm might not have the `.venv` directory included in its content roots, preventing it from recognizing the packages.
- **The Solution:**
    - Open PyCharm's settings and navigate to Project: [Your Project Name] > Project Structure.
    - Ensure that the `.venv` directory is listed as a content root. If not, click "Add Content Root" and select the `.venv` directory.

**4. PyCharm's venv detection issues:**

- **The Problem:** PyCharm sometimes struggles to detect a venv that was created by a tool it did not create itself.
- **The Solution:**
    - If possible, create the venv using pycharm. This will guarantee that the pycharm knows where the venv is.
    - If using uv is desired, then double check the pycharm project interpreter settings, and invalidate the caches.

**Troubleshooting Steps:**

1. **Verify the `.venv`:** Double-check that the `.venv` directory exists in your project's root and that the FastAPI package is indeed installed there. You can do this by activating the virtual environment and running `pip list` or `uv list`.
2. **Restart PyCharm:** After making any changes to the interpreter settings, restart PyCharm to ensure that the changes take effect.
3. **Check for Errors:** Look for any error messages in PyCharm's event log or console that might provide clues about the problem.

By carefully checking these settings, you should be able to resolve the issue and get PyCharm to recognize your FastAPI installation.

2.5 Debug4: Check project interpreter

So I checked the pycharm’s project python interpreter:

It’s really not the .venv in my project, so I changed it to uv’s .venv directory:

Then ,you can see that the fastapi is back.

2.6 Check the code

Now let’s check the code:

Now it compiles ok, it works!

3. Summary

In this post, I demonstrated how to correctly use uv to install packages in pycharm. That’s it, thanks for your reading.

Final Words + More Resources

My intention with this article was to help others who might be considering solving such a problem. So I hope that’s been the case here. If you still have any questions, don’t hesitate to ask me by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 uv github
👨‍💻 Introduction to uv

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!