Configure a uv environment
The uv tool makes Python development easier, reducing setup tasks for new projects and helping manage existing ones.
To use uv in PyCharm, you need to install it on your machine and create a specific Python environment.
When you select uv while creating a new Python project, PyCharm automatically generates a pyproject.toml file. This file specifies required packages, scripts, plugins, and URLs. See the pyproject guide to learn more about its structure and format.
A uv environment stores the list of its dependencies in one file, and that file sets how PyCharm manages the packages:
pyproject.toml: the environment is a uv project. PyCharm creates the project with
uv init, records the dependencies withuv add, and installs them withuv syncaccording to the uv.lock file.A requirements file, requirements.txt by default: PyCharm manages the packages with
uv pip, and the environment has no lock file.
The New Project wizard always creates a uv project. In the Add Interpreter dialog, the Use pyproject.toml (uv init) checkbox sets the mode, and you can change the mode of an environment later. Refer to Manage the dependencies of a uv environment.
Create a uv environment
Do one of the following:
Click the Python Interpreter selector and select Settings.
Press Ctrl+Alt+S to open Settings and navigate to .
If the project contains subprojects, select the subproject in the list on the left.
Click
Add Interpreter… next to the Interpreter list and select Add Local Interpreter….
The following actions depend on whether you want to generate a new virtual environment or to use an existing one.
- New uv environment
Select uv from the list of environment types.
Select the Python version from the list.
PyCharm will detect a uv installation.
If PyCharm did not detect the installation automatically, specify the location of the uv executable, or click
to browse for it.
Select Use pyproject.toml (uv init) to create a uv project. PyCharm selects this checkbox when the project directory already contains a pyproject.toml file.
Clear the checkbox to keep the dependencies in requirements.txt and manage the packages with
uv pip.
- Existing uv environment
Select uv from the list of environment types.
PyCharm will detect a uv installation.
If PyCharm did not detect the installation automatically, specify the location of the uv executable, or click
to browse for it.
Select the environment from the list.
Select or clear the Use pyproject.toml (uv init) checkbox to set how PyCharm manages the dependencies of this environment.
The selected uv environment will be reused for the current project.
Click OK to complete the task.
After you configure a uv environment, you can run your project from the terminal, or from a Python run/debug configuration that has the Run with uv run option enabled.
Manage the dependencies of a uv environment
Open the dependency file of the environment in the editor and use the actions on the banner at the top of the editor. The available actions depend on the mode of the environment.
uv Lock: update uv.lock to match the dependencies in pyproject.toml.
uv Sync: install the packages that uv.lock names into the environment.
Switch to uv Pip Mode: store a requirements file as the dependency list and manage the packages with
uv pipfrom now on. PyCharm stores the open requirements file, or requirements.txt when you run the action from pyproject.toml.
For more information, refer to Update the lock file.
uv pip Install: install the packages that the requirements file names. The packages that the file does not name stay in the environment.
uv pip Sync: make the environment match the requirements file. PyCharm removes the packages that the file does not name.
Switch to uv Project Mode: store pyproject.toml as the dependency list. When the project directory has no pyproject.toml file, PyCharm creates one with
uv init.Set as the Environment Dependencies List: store the open requirements file as the dependency list of the environment. This action is available for a requirements file other than the stored one.
In the Python Packages tool window, Install requirements installs the packages that the stored requirements file names.
The same actions are available in the Python interpreter widget popup on the status bar.
uv workspace support
PyCharm supports uv workspaces and uv path dependencies. When you open a project with the Workspace mode enabled, PyCharm automatically sets up the workspace members and their dependencies.
uv workspaces use a single virtual environment shared across all projects, while uv path dependencies give each project its own virtual environment.
Once a .py or pyproject.toml file is opened in a workspace member, PyCharm checks whether an environment for this workspace already exists on the system. If it does, the environment is automatically set as the SDK. If not, a file-level notification suggests creating a new uv environment and installing dependencies for this workspace member.
PyCharm verifies environment consistency and warns you if a dependency defined in pyproject.toml is missing from the environment. A quick-fix is provided to install the missing dependency. If a package is imported but not listed in the workspace member's pyproject.toml, a quick-fix suggests adding the package to the environment and updating the corresponding .toml file.
The dependencies between workspace members are visually presented in as read-only. To make changes, edit the pyproject.toml file manually.
For more information, refer to Workspaces and monorepos.
For any of the configured Python interpreters (but Docker-based), you can: