Skip to content

How to configure PyCharm for a uv project

by Tim Hopper · Markdown
uv
This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

PyCharm needs two things to work well with a uv project: the right Python interpreter and, for monorepos, an understanding of the workspace layout. This guide covers the interpreter setup first, then the newer workspace support.

Create the environment

uv creates a virtual environment in .venv/ at the project root. Create it (and install dependencies) before pointing PyCharm at it:

uv sync

This reads pyproject.toml and uv.lock, builds .venv/, and installs every dependency into it. PyCharm needs this directory to exist before it can use the environment.

Select the uv interpreter

PyCharm 2024.3.2 and later list uv as an environment type, so you point the IDE at the .venv uv already created rather than configuring a raw interpreter path.

  1. Open Settings: PyCharm | Settings on macOS (Cmd+,) or File | Settings on Windows and Linux (Ctrl+Alt+S).
  2. Go to your project’s Python Interpreter page.
  3. Click Add Interpreter, then Add Local Interpreter.
  4. Select uv from the list of environment types. PyCharm auto-detects the uv executable on your PATH; if it doesn’t, point it at the executable with the browse button.
  5. Choose the existing environment (the .venv uv created) and click OK.

PyCharm indexes the environment and resolves imports against the packages uv installed. The exact wording of these dialogs shifts between releases; the JetBrains uv documentation tracks the current UI.

Tip

If you add a dependency with uv add and PyCharm still flags the import as unresolved, run uv sync so the package lands in .venv, then let PyCharm re-index. The interpreter watches the environment, not your pyproject.toml.

Manage a uv workspace (PyCharm 2026.1.1 beta)

PyCharm 2026.1.1 added beta support for uv workspaces, so a monorepo with several packages under one [tool.uv.workspace] root is understood as a single project rather than a folder of unrelated code.

The feature is opt-in. According to the JetBrains announcement, when you open a project with a compatible workspace configuration, PyCharm offers to enable workspace management, and you can toggle it later under Settings | Project Structure. Once enabled:

  • PyCharm derives the member layout and dependency graph from pyproject.toml. The graph appears under Settings | Project Dependencies as read-only references; to change a relationship, edit pyproject.toml and PyCharm updates its model.
  • If a compatible environment already exists, PyCharm configures it as the interpreter automatically. If none exists, a file-level notification offers to create one.
  • When an import has no matching entry in pyproject.toml, PyCharm flags it and offers a Sync project quick-fix that runs the sync and updates the file.
  • The Python Process Output tool window shows every command PyCharm runs and its live output, so a failed sync is something you can read rather than guess at.

PyCharm applies the same workspace flow to Poetry and Hatch projects, defaulting to uv when it is installed.

Note

This is beta and tied to PyCharm 2026.1.1. Dialog names and behavior may change before the feature ships as stable. The interpreter setup in the previous section works on every supported PyCharm version and does not depend on this feature.

Enable Ruff

PyCharm 2025.3 and later ship built-in Ruff support that reads your project’s pyproject.toml or ruff.toml, so the editor and the command line stay consistent. On earlier versions, install the community Ruff plugin from the marketplace. The Ruff editor setup documentation covers both paths and the current settings.

Run uv add --dev ruff so the same Ruff version is available on the command line and in CI.

Run pytest

PyCharm discovers and runs pytest tests when pytest is installed in the project interpreter and set as the default test runner. Add it as a development dependency:

uv add --dev pytest

Set pytest as the test runner under PyCharm’s Python integrated tools settings, then run tests from the gutter icons or the test tool window. The JetBrains testing documentation covers pytest setup.

Troubleshooting

Unresolved imports: Run uv sync, then confirm the project interpreter points at the project’s .venv rather than a global Python.

Wrong Python version: Compare the version PyCharm shows for the interpreter against uv python pin. If they differ, re-select the uv environment in Settings.

uv not detected: PyCharm looks for the uv executable on your PATH. If you installed uv outside a standard location, point the interpreter dialog at the executable with the browse button. See How to install uv.

Learn More

Last updated on
How to configure mypy strict modeHow to configure recommended Ruff defaults