Configure projects in PyCharm
Configure a Python interpreter

Configure a Python interpreter

Last modified: 13 October 2021

Project interpreter:

File | Settings | Project | Python Interpreter for Windows and Linux

PyCharm | Preferences | Project | Python Interpreter for macOS

Default project interpreter:

File | New Projects Setup | Settings for New Project for Windows and Linux

File | New Projects Setup | Preferences for New Project for macOS

Python interpreters in PyCharm

To work with your Python code in PyCharm, you need to configure at least one Python interpreter. You can use a system interpreter that is available with your Python installation. You can also create a Virtualenv, Pipenv, or Conda virtual environment. A virtual environment consists of a base interpreter and installed packages.

With PyCharm Professional, you can also configure interpreters to execute your Python code on remote environments: SSH, Vagrant, WSL (only for Windows), Docker, and Docker Compose

When you configure a Python interpreter, you need to specify the path to the Python executable in your system. So, before configuring a Python interpreter, you need to ensure that you've downloaded Python and installed it in your system and you're aware of a path to it. You can create several Python interpreters based on the same Python executable. This is helpful when you need to create different virtual environments for developing different types of applications. For example, you can create one virtual environment based on Python 3.6 to develop Django applications and another virtual environment based on the same Python 3.6 to work with scientific libraries.

Python interpreters can be configured for a new project or for the current project (you can create a new interpreter or use one of the existing interpreters).

Setting an existing Python interpreter

At any time, you can switch your Python interpreter either using the Python Interpreter selector or in the project Settings/Preferences.

Change the Python interpreter using the Python Interpreter selector

The Python Interpreter selector is located on the status bar. It is the most convenient and quickest way to switch the Python interpreter. Just click it and select the target interpreter:

Change the Python interpreter in the project settings

Press Ctrl+Alt+S to open the IDE settings and select Project <project name> | Python Interpreter.
Expand the list of the available interpreters and click the Show All link. Alternatively, click the icon and select Show All.
Select the target interpreter.
When PyCharm stops supporting any of the outdated Python versions, the corresponding Python interpreter is marked as unsupported.

When you change an SSH interpreter, you might need to synchronize local content with the target server. Mind a notification balloon in the lower-right corner.

Sync local files with the deployment server

You can click one of the links to perform the following actions:

Auto-upload files to the server
Synchronize files and then enable auto-uploading

Modify a Python interpreter

Press Ctrl+Alt+S to open the IDE settings and select Project <project name> | Python Interpreter.
Expand the list of the available interpreters and click the Show All link. Alternatively, click the icon and select Show All.
Select the target interpreter and click Edit.
You can specify an alternative interpreter name for the selected interpreter. The Python interpreter name specified in the Name field, becomes visible in the list of available interpreters. Click OK to apply the changes.
For remote interpreters (that are available in PyCharm Professional) you can modify configuration parameters.
warning
When you modify an SSH interpreter, PyCharm shows the parameters of the corresponding Deployment configuration. It is not recommended selecting the SSH option as it doesn't allow file synchronization and is part of the legacy implementation.

Creating a new Python interpreter

To add a new interpreter to the current project:

Do one of the following:
- Click the Python Interpreter selector and choose Add Interpreter.
- Press Ctrl+Alt+S to open the project Settings/Preferences and go to Project <project name> | Python Interpreter. Then click the icon and select Add.
Choose the interpreter type to add and perform the specific settings:
warning
Note that SSH, WSL, Vagrant, Docker, and Docker Compose are available only for the commercial version of PyCharm. WSL is Windows specific.
Virtualenv
Pipenv
Conda
System
SSH
Vagrant
WSL
Docker
Docker Compose
1. In the left-hand pane of the Add Python Interpreter dialog, select Virtualenv Environment. The following actions depend on whether the virtual environment existed before.
  If New environment is selected:
  Specify the location of the new virtual environment in the text field, or click and find location in your file system. Note that the directory where the new virtual environment should be located, must be empty!
  Choose the base interpreter from the list, or click and find a Python executable in the your file system.
  If PyCharm detects no Python on your machine, it provides two options: to download the latest Python versions from python.org or to specify a path to the Python executable (in case of non-standard installation).
  Select the Inherit global site-packages checkbox if you want that all packages installed in the global Python on your machine to be added to the virtual environment you're going to create. This checkbox corresponds to the --system-site-packages option of the virtualenv tool.
  Select the Make available to all projects checkbox if you want to reuse this environment when creating Python interpreters in PyCharm.
  If Existing environment is selected:
  Expand the Interpreter list and select any of the existing interpreters. Alternatively, click and specify a path to the Python executable in your file system, for example, C:\Python36\python.exe.
  Select the Make available to all projects checkbox if you want to reuse this environment when creating Python interpreters in PyCharm.
2. Click OK to complete the task.
See Configure a virtual environment for more details.

When a remote Python interpreter is added, at first the PyCharm helpers are copied to the remote host. PyCharm helpers are needed to run remotely the packaging tasks, debugger, tests and other PyCharm features. Next, the skeletons for binary libraries are generated and copied locally. Also all the Python library sources are collected from the Python paths on a remote host and copied locally along with the generated skeletons. Storing skeletons and all Python library sources locally is required for resolve and completion to work correctly. PyCharm checks remote helpers version on every remote run, so if you update your PyCharm version, the new helpers will be uploaded automatically and you don't need to recreate remote interpreter. SFTP support is required for copying helpers to the server.

Setting the default interpreter

In PyCharm, you can specify an interpreter that will be automatically set for all newly created projects.

From the main menu, select File | New Projects Setup | Settings for New Projects (on Window and Linux) or File | New Projects Setup | Preferences for New Projects (on macOS).
Select Python Interpreter settings. Then either choose an existing interpreter from the Python interpreter list of click to add a new interpreter. Click OK to save the changes.
The change will become effective for all newly created projects in PyCharm.

Managing interpreter packages

For each interpreter, you can install, upgrade, and delete Python packages. By default, PyCharm uses pip to manage project packages. For Conda environments you can use the Conda package manager.

PyCharm smartly tracks the status of packages and recognizes outdated versions by showing the number of the currently installed package version (column Version), and the latest available version (column Latest version). When a newer version of a package is detected, PyCharm marks it with the arrow sign and suggests to upgrade it.

By default, the Latest version column shows only stable versions of the packages. If you want to extend the scope of the latest available versions to any pre-release versions (such as beta or release candidate), click Show early releases.

You can upgrade several packages at once. Hold Cmd (macOS) or Ctrl on (Unix or Windows), left-click to select several items in the list of packages, and then click Upgrade.

See the detailed instructions:

How to install a package
How to upgrade the package
How to uninstall the package

Configure a Python interpreter﻿

Python interpreters in PyCharm﻿

Setting an existing Python interpreter﻿

Change the Python interpreter using the Python Interpreter selector﻿

Change the Python interpreter in the project settings﻿

Modify a Python interpreter﻿

warning

Creating a new Python interpreter﻿