# How to configure PyCharm for a uv project {{< callout type="warning" >}} This guide assumes you have a Python project managed with [uv](https://pydevtools.com/handbook/reference/uv.md). If you haven't created a project yet, see the [project creation tutorial](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md). {{< /callout >}} PyCharm needs two things to work well with a [uv](https://pydevtools.com/handbook/reference/uv.md) 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](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) in `.venv/` at the project root. Create it (and install dependencies) before pointing PyCharm at it: ```bash 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](https://www.jetbrains.com/help/pycharm/uv.html) 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](https://pydevtools.com/handbook/how-to/how-to-set-up-a-python-monorepo-with-uv-workspaces.md), 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](https://blog.jetbrains.com/pycharm/2026/05/support-for-uv-poetry-and-hatch-workspaces-beta/), 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](https://pydevtools.com/handbook/reference/poetry.md) and [Hatch](https://pydevtools.com/handbook/reference/hatch.md) 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](https://pydevtools.com/handbook/reference/ruff.md) 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](https://docs.astral.sh/ruff/editors/setup/) 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](https://pydevtools.com/handbook/reference/pytest.md) tests when pytest is installed in the project interpreter and set as the default test runner. Add it as a development dependency: ```bash 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](https://www.jetbrains.com/help/pycharm/pytest.html) 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](https://pydevtools.com/handbook/how-to/how-to-install-uv.md). ## Learn More - [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does and the core workflows. - [How to set up a Python monorepo with uv workspaces](https://pydevtools.com/handbook/how-to/how-to-set-up-a-python-monorepo-with-uv-workspaces.md) - [Configure a uv environment (JetBrains)](https://www.jetbrains.com/help/pycharm/uv.html) - [uv, Poetry, and Hatch workspace support in PyCharm](https://blog.jetbrains.com/pycharm/2026/05/support-for-uv-poetry-and-hatch-workspaces-beta/) - [How to configure VS Code for a uv project](https://pydevtools.com/handbook/how-to/how-to-configure-vs-code-for-a-uv-project.md)