In PyCharm, press Ctrl+Alt+S to open Settings, go to Python | Interpreter and click Add Interpreter. Choose Add Local Interpreter, then pick an environment type such as Virtualenv and a base interpreter. That’s just a Python executable already installed on your machine.
PyCharm won’t work with your Python code until at least one interpreter is configured (JetBrains Help, PyCharm 2026.2). A virtual environment is a base interpreter plus whatever packages you install into it.
One installed Python can back several environments. The same documentation describes a Python 3.12 environment for Django and a second one for scientific libraries, both built from a single executable.
How to Add a Python Interpreter in PyCharm
A project interpreter is the Python runtime together with the packages installed for it. PyCharm reads it to resolve imports and complete code, and it’s also what runs your scripts.
The status bar is the quicker route. Click the Python Interpreter selector there and choose Add New Interpreter.
Settings works too. Press Ctrl+Alt+S (on macOS, open Settings from the PyCharm menu) and select Python | Interpreter.
Where that page lives depends on your version. Older PyCharm releases nest it under Project: <project name> | Python Interpreter, while the PyCharm 2026.2 documentation (page dated 15 September 2026) puts it at the top level as Python | Interpreter.
For a new Virtualenv, the dialog goes like this.
- Click Add Interpreter next to the interpreter list, then select Add Local Interpreter.
- Choose Virtualenv from the environment types.
- Pick the base interpreter from the dropdown, or browse to the Python executable.
- Set the Location of the new environment. The directory must be empty.
- Tick the two optional checkboxes only if you need them.
- Click OK. The environment is created and selected for the project.
The first checkbox, Inherit packages from base interpreter, adds every package from the global Python to the new environment. It maps to the –system-site-packages option of virtualenv. The second, Make available to all projects, lets you reuse this environment when you create interpreters for other projects.
Leave the first box off. Global packages leak into the project and hide anything missing from requirements.txt.
There’s a longer guide to creating a virtual environment in PyCharm if the basics here aren’t enough.
Where to Find the Base Interpreter Path on Windows, macOS and Linux
PyCharm builds an environment from a Python executable, and the base interpreter path is the full path to that file. It’s python.exe on Windows and python3 on macOS and Linux.
Python has to be installed before PyCharm can use it, so download it from python.org first (JetBrains Help, PyCharm 2026.2).
- On Windows, run where python in Command Prompt, or py –list-paths to list python.org installs. A per-user install typically sits in C:\Users\your-name\AppData\Local\Programs\Python\Python311\python.exe.
- On macOS, run which python3. Homebrew on Apple silicon puts the file at /opt/homebrew/bin/python3.
- Linux works the same way with which python3, and the distribution’s own copy usually lives at /usr/bin/python3.
One Windows trap catches a lot of developers. The python.exe in the WindowsApps folder is often a zero-byte shortcut to the Microsoft Store, and a JetBrains support thread shows PyCharm answering it with “Failed to create interpreter”.
Microsoft Learn (updated 14 September 2026) says a python.org install with the add-to-PATH option takes priority over that shortcut. You can also switch the shortcut off under Manage app execution aliases.
Another classic mistake is browsing to pycharm64.exe, which gets “invalid interpreter name”. PyCharm is the editor, not the interpreter.
Pick a supported release for new environments. Python 3.10 reached end of life on 1 October 2026, while 3.11 through 3.14 were still supported at the Python Developer’s Guide’s 27 May 2026 update.
The install-first rule has an exception. PyCharm 2025.3 lets you pick a Python version from a list for a uv environment, and uv uses the matching system version or downloads one (JetBrains, What’s New in PyCharm 2025.3).
uv downloads Python automatically by default. Setting python-downloads to manual turns that off, according to uv’s documentation (page dated 1 October 2026).
For Virtualenv, Pipenv, Poetry and Hatch, where you choose a base interpreter, the install-first rule still holds.
Which Interpreter Type Fits Your Project?
Let the project’s existing files decide. A Pipfile means Pipenv, and a Poetry-managed pyproject.toml means Poetry. An environment.yml points to Conda, a uv project to uv, and a bare requirements.txt to Virtualenv.
The PyCharm 2026.2 documentation counts seven local types: system interpreter, Virtualenv, Conda, Pipenv, Poetry, uv and Hatch. The table folds Pipenv in with Poetry and uv in with Hatch to keep it short.
| Type | Best for | Watch out for |
|---|---|---|
| System interpreter | Single scripts, quick checks | Packages install into the global Python and mix across projects |
| Virtualenv | Projects with a requirements.txt | The target folder must be empty |
| Conda | Scientific stacks with native dependencies | Anaconda or Miniconda must be installed first |
| Pipenv or Poetry | Projects that already have a Pipfile or Poetry setup | Packages install through the tool, not pip |
| uv or Hatch | Fast setup and managed Python versions with uv, named project environments with Hatch | Each tool’s executable must be detected or located |
The remote types (WSL, SSH, Docker and Docker Compose) need PyCharm Pro and get their own section below.
Survey data shows how developers split on isolation tools. venv leads at 62% among tools used to isolate environments, followed by virtualenv (25%), Conda (19%), Poetry (18%) and uv (11%). That comes from the Python Developers Survey 2024 by the PSF and JetBrains, collected in October and November 2024.
Skip the system interpreter for anything with dependencies. Among developers who build for the cloud, 51% develop locally with virtualenv and only 19% use the local system interpreter (same survey).
The tools differ in ways the dialog never shows, so a comparison of venv, Conda and Poetry is worth a read before you commit a team to one.
PyCharm Community and Professional merged into one product with PyCharm 2025.1, and 2025.2 was the last Community release (JetBrains Help). In the 2026.2 documentation, only the remote interpreter types are tied to Pro.
Since PyCharm 2025.3, the New Project wizard suggests uv as the default environment manager when uv is installed. PyCharm keeps an earlier choice of venv, Conda or Poetry, and uv projects run with uv run by default in run configurations (JetBrains, What’s New in PyCharm 2025.3).
Using an Existing Environment, Conda, Poetry, uv, Pipenv or Hatch
For an existing environment, select its Python executable. For the other managers, choose the type in Add Local Interpreter and let PyCharm detect the tool.
Existing virtualenv
Choose Python from the list of environment types, then select the interpreter from the list. If it’s missing, click the three-dot button and browse to the executable.
On macOS and Linux that’s venv/bin/python. On Windows it’s venv\Scripts\python.exe.
PyCharm reuses the selected environment for the current project. If the Invalid environment warning shows up, the binary is missing at that path or the Python version is unsupported (JetBrains Help, PyCharm 2026.2).
Conda
Conda needs Anaconda or Miniconda installed before the dialog can do anything.
- Select Conda from the environment types
- PyCharm detects the installation, or you point it to the conda executable
- For a new environment, pick a Python version and give it a name
- For an existing one, select it from the list
PyCharm can use the conda package manager for these environments, where other types default to pip.
Poetry and Pipenv
For Poetry, pick the base interpreter and let PyCharm detect the installation. If detection fails, an Install poetry via pip button appears, or you can browse to the executable. A project that already has a Poetry environment can reuse it by choosing the existing one from the list.
Pipenv starts the same way with a base interpreter. PyCharm autodetects the executable when the base binary directory is on PATH, and an Install pipenv via pip button covers the rest.
Packages in a Pipenv interpreter come from the Pipfile and install, update and uninstall through pipenv, not pip (JetBrains Help). Running pip by hand in that environment bypasses the Pipfile.
uv and Hatch
Both follow the same dialog flow as Poetry, with a few differences.
With uv, you pick a Python version from the list for a new environment. PyCharm detects uv or asks you for the executable location.
Hatch asks you to select a Hatch environment, and if you pick none, Hatch uses its default environment. You also choose the base interpreter, as you would for Virtualenv.
Once the environment is attached, installing packages in PyCharm uses the same package list for every type, with the package manager changing underneath.
Remote Interpreters on WSL, SSH and Docker
WSL, SSH, Docker and Docker Compose interpreters run your code outside the local Python, and all four need PyCharm Pro (JetBrains Help, PyCharm 2026.2).
When you add one, PyCharm copies its helpers to the remote host. Those helpers run the debugger, tests and packaging tasks there.
PyCharm then generates skeletons for binary libraries, collects the Python library sources from the remote paths and copies both locally. Resolve and completion depend on that local copy.
After a PyCharm update, new helpers upload on the next remote run, so you never recreate the interpreter for that.
Among developers who build for the cloud, 44% develop in Docker containers, 15% use WSL and 16% work in remote development environments, according to the 2024 Python Developers Survey.
WSL interpreter
WSL works on Windows only. In the Add Interpreter list choose On WSL, wait for PyCharm to detect Linux and finish introspection, then click Next.
A few things need to be in place first.
- Turn on the Python, FTP/SFTP/WebDAV Connectivity, SSH Remote Run and Remote Execution Agent plugins
- Install WSL and initialize a Linux distribution
- Install rsync if the distribution lacks it (sudo apt install rsync on Debian-based systems)
On the next screen pick a Virtualenv, Conda, Pipenv, Poetry, uv or Hatch environment. PyCharm sets the default mnt mappings and also detects custom WSL distributions.
WSL 2 has known issues. The debugger does not work properly when the firewall is not opened for the WSL IP address (JetBrains Help, 17 August 2026).
For the terminal, set the Shell path to wsl.exe under Tools | Terminal, then run source .venv/bin/activate to activate the environment.
SSH interpreter
The remote host must run an SSH server, because PyCharm runs the interpreter through SSH sessions. A Windows machine can’t be the remote host.
You enter the host, port and username, or reuse an existing SSH configuration. Authentication is either a password or a key pair (OpenSSH or PuTTY), in which case you give the private key location and passphrase. Last, pick a new or existing Virtualenv, Conda, Pipenv, Poetry, uv or Hatch environment.
The SSH configuration you create also appears in SSH Deployment Configurations, so one setup serves both.
Docker and Docker Compose interpreters
Select On Docker, pick a Docker server (or create a connection to the Docker daemon), then choose how the image arrives.
Docker has to be installed before any of this works, so start with a guide on installing Docker if the machine does not have it yet.
To pull or reuse an image, enter its tag, such as python:3.12. To build one, point PyCharm at a Dockerfile and a context folder, with an optional image tag, build options and build args.
The first setup needs a stable internet connection, because PyCharm downloads busybox:latest. After a successful setup you can go offline (JetBrains Help).
A few things don’t work. You can’t install Python packages into a Docker-based interpreter. On Windows and macOS, volumes and bind mounts outside the mapped local path are unavailable, and every run, debug, coverage or test execution creates a new container.
On a Linux host Docker runs natively, so the path mapping limit does not apply.
A Docker Compose interpreter starts from a docker-compose.yml file instead. You select the server, the configuration file and the service, and PyCharm builds the target from there.
If you have never run a service that way, this explainer on defining services with Docker Compose covers the file itself.
How to Check, Switch and Remove an Interpreter
The status bar shows the active interpreter, the package list shows what it contains, and a short script proves PyCharm runs the Python you expect.
Check that the interpreter works
The Python Interpreter selector in the status bar shows which interpreter is attached to the project. The package list lives under Settings | Python | Interpreter, or under View | Tool Windows | Python Packages for the currently selected interpreter.
For a real test, run import sys, then print(sys.executable) and print(sys.prefix != sys.base\_prefix).
A correct state looks like this. The executable path points inside your environment folder, the comparison prints True, and the package list holds only what you installed.
Python’s venv documentation (updated 6 October 2026) calls the prefix comparison sufficient to tell whether code runs from a virtual environment.
Switch to a different interpreter
The status bar selector is the fastest switch. Click it and pick the target interpreter.
- Press Ctrl+Alt+S and open Python | Interpreter.
- Open the interpreter dropdown and choose the one you want.
- If it is missing, click Show All and select it in the left pane.
- Click OK.
Moving a project to a newer Python means creating an environment on the new base interpreter and switching to it. A separate guide covers changing the Python version in PyCharm.
Switching to an SSH interpreter can trigger a balloon in the lower-right corner about syncing local files with the server. Auto-upload files starts uploading on the next save, while Sync and auto-upload files syncs immediately and then uploads on every save.
Modify or remove an interpreter
Open Python | Interpreter, expand the list and click Show All. Every edit below starts there.
| Task | Where | Effect |
|---|---|---|
| Rename | Select the interpreter, click the edit icon, change Name | New name shows in the interpreter list |
| Change the path | Edit the Interpreter path field | Entry points at a different executable |
| Limit to one project | Tick Associate this virtual environment with the current project | Interpreter is available only in this project |
| Remove | Select the interpreter, click the remove icon | Entry leaves the project settings |
JetBrains describes removal as taking the interpreter out of the project settings. Python’s venv documentation treats an environment as disposable, so deleting the folder and recreating it is normal.
Clearing the folder itself is a separate step, and there’s a guide to deleting a venv.
Why Does PyCharm Show an Invalid or Missing Interpreter?
PyCharm flags an interpreter as invalid when the Python binary is not at the configured path, when its Python version is no longer supported, or when the project has no interpreter at all.
| Symptom | Cause | Fix |
|---|---|---|
| Invalid environment warning | Binary not found at the path, or unsupported Python version | Correct the path or install a supported Python |
| Interpreter invalid after moving the project | The environment folder moved, and venvs are not movable | Recreate the environment in the new location |
| Warning on every .py file | The offer to create an environment was ignored, so no interpreter exists | Add an interpreter, or create one from requirements.txt |
| Interpreter marked unsupported | PyCharm dropped support for that older Python version | Create a new environment on a supported base interpreter |
| Imports fail after switching | Each interpreter has its own set of packages | Install from requirements.txt in the new environment |
| Script may lack full write access to TEMP or the registry | Python came from the Microsoft Store, whose app restrictions can limit write access to shared locations such as those | Switch to a python.org install |
After moving a project folder
JetBrains says the Invalid environment warning means PyCharm cannot find the binary at the specified path. Python’s venv documentation says virtual environments are not movable or copyable. Read together, they explain this failure from both ends.
The cause is absolute paths. Scripts installed in an environment carry shebang lines that point to its interpreter, so a moved folder leaves them pointing at the old location.
The fix is to recreate the environment in the new location and delete the one at the old location.
- Open Python | Interpreter, click Show All and remove the stale entry.
- Add a new Virtualenv in the new location, or accept PyCharm’s offer to create one from requirements.txt.
- Install the dependencies. PyCharm prompts you to install the packages listed in a requirements.txt file added to the project.
- Delete the old environment folder.
This only works when the project lists its dependencies. A project without a requirements.txt has nothing to rebuild from, so run pip freeze > requirements.txt in a working environment first (JetBrains Help).
When no interpreter is configured at all
Ignoring PyCharm’s offer to create an environment leaves the project without an interpreter. Every .py file you open then shows a warning with options for configuring one (JetBrains Help, PyCharm 2026.2).
Use the options in the warning, or open Python | Interpreter and choose Add Local Interpreter.
The offer to create an environment shows up when you open a directory that contains a requirements.txt or setup.py file.
When the cause isn’t obvious, PyCharm 2025.3 added a Python Process Output tool window for reading the real error. It lists every command the IDE ran with its input, output and error streams, and it replaces modal error dialogs while a project is open (JetBrains, What’s New in PyCharm 2025.3).
FAQ About the Python Interpreter in PyCharm
Do I need a Pro subscription to add a Python interpreter?
No, not for local interpreters. Only the remote types (SSH, Docker, Docker Compose and WSL) need PyCharm Pro, and installing the unified PyCharm starts a 30-day Pro trial that covers them (JetBrains Help, PyCharm 2025.3).
How do I set a default interpreter for new projects?
Go to File | New Projects Setup | Settings for New Projects and open the Python Interpreter settings. Pick an existing interpreter or add a new one, then click OK.
PyCharm also applies it to existing projects without an .idea folder the first time you open them.
How do I install packages after adding an interpreter?
Open View | Tool Windows | Python Packages, search for the package and click Install. The tool window works on the currently selected interpreter and uses pip by default.
Conda environments can install from the conda repository instead.
How can I reuse installed packages in another project?
Create a virtual environment that holds the packages, then select it as the interpreter of the other project.
Or run pip freeze > requirements.txt, add the file to the target project, and PyCharm prompts you to install the listed packages (JetBrains Help, PyCharm 2026.2).
Does PyCharm detect Python versions managed by asdf?
Yes, since PyCharm 2025.3 the IDE detects Python versions managed by asdf automatically, so you can select them without extra setup (JetBrains, What’s New in PyCharm 2025.3).
Any other installed Python still works if you browse to its executable.
Giving Teammates the Same Python Interpreter in PyCharm
Teammates get the same Python interpreter in PyCharm by recreating the environment from a committed dependency file, because the environment folder itself stays out of version control.
Environments created with venv on Python 3.13 or later carry their own .gitignore, so Git skips the folder.
Commit requirements.txt or setup.py. Your teammate opens the cloned folder and accepts the environment offer, then confirms the interpreter in the status bar selector.
Dependency information lives in requirements.txt for 59% of developers and in pyproject.toml for 36%, per the 2024 Python Developers Survey (PSF and JetBrains).
The PyCharm 2026.2 documentation names only requirements.txt and setup.py as triggers for the offer. A pyproject.toml project should add its interpreter through the Poetry or uv type.
Verified on 7 October 2026, and the advice changes if PyCharm adds trigger files. Next up is running code in PyCharm.
- Show Hidden Characters, Spaces, and Line Endings in Notepad++ - October 19, 2026
- Military and Defense UI/UX Design Services Firms to Know in 2026 - October 19, 2026
- How to Manage Your Google Play Subscriptions - October 17, 2026
