PyCharm 2019.1 Help

Configure a Python interpreter

In PyCharm you are not limited to using just any single Python interpreter. You are able to implement several and in doing so choose which interpreter you wish to use for any specific project.

PyCharm supports:

Python interpreters can be configured on the following levels:

  • Current project: selected Python interpreter will be used for the current project.

    Configuring Python interpreter on this level is described below. You can create a new interpreter or use one of the existing interpreters.

  • New project: selected Python interpreter will be used for the new project instead of the default one.

    Refer to the section Create a pure Python project.

Creating a new project interpreter

To add a new interpreter to the current project:

  1. Open the Add Python Interpreter dialog by either way:

    • When you're in the Editor, the most convenient way is to use the Python Interpreter widget in the Status bar. Click the widget and select Add Interpreter ...

    • If you are in the Settings/Preferences dialog (Ctrl+Alt+S), select Project <project name> | Project Interpreter. Click the The Configure project interpreter icon and select Add.

  2. Choose the interpreter type to add and perform the specific settings:

    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:

    1. Specify the location of the new virtual environment in the text field, or click Virtual environment location and find location in your file system. Note that the directory where the new virtual environment should be located, must be empty!

    2. Choose the base interpreter from the list, or click Choose the base interpreter and find the base interpreter in the your file system.

    3. Select the Inherit global site-packages checkbox if you want to inherit your global site-packages directory. This checkbox corresponds to the --system-site-packages option of the virtualenv tool.

    4. Select the Make available to all projects checkbox, if needed.

    If Existing environment is selected:

    1. Specify the required interpreter: use the list, or click Select an interpreter and find one in your file system.

    2. Select the checkbox Make available to all projects, if needed.

    Click OK to complete the task.

    See Configure a virtual environment for more details.

    If you have added the user base’s binary directory to your PATH environmental variable, you don't need to set any additional options: the path to the pipenv executable will be autodetected:

    Path to the pipenve executable is autodetected

    Click OK to complete the task.

    If you have not modified the PATH variable, PyCharm shows an error message: Pipenv executable is not found. Discover the proper executable path as described in the pipenv installation procedure and enter the target string in the Pipenv executable field, for example: C:\Users\jetbrains\AppData\Roaming\Python\Python37\Scripts\pipenv.exe (Windows) or /Users/jetbrains/.local/bin/pipenv (macOS).

    Click OK to save the changes and complete the task.

    See Configure a Pipenv environment for more details.

    In the left-hand pane of the Add Python Interpreter dialog, select Conda Environment. The following actions depend on whether the Conda environment existed before.

    If New environment is selected:

    1. Specify the location of the new Conda environment in the text field, or click Conda environment location and find location in your file system. Note that the directory where the new Conda environment should be located, must be empty!

    2. Select the Python version from the list.

    3. Specify the location of the Conda executable file in the text field, or click Conda executable location and find location in the Conda installation directory.

    4. Select the Make available to all projects checkbox, if needed.

    If Existing environment is selected:

    1. Specify the required interpreter: use the list, or click Select an interpreter and find one in your file system (for example, C:\Users\jetbrains\Anaconda3\python.exe).

    2. Select the checkbox Make available to all projects, if needed.

    Click OK to complete the task.

    See Configure a Conda virtual environment for more details.

    In the left-hand pane of the Add Python Interpreter dialog, select System Interpreter.
    Adding a system interpreter
    In the Interpreter field, type the fully-qualified path to the required interpreter executable, or click Browse icon and in the Select Python Interpreter dialog that opens, choose the desired Python executable and click OK. Note that you will need admin privileges to install, remove, and upgrade packages for the system interpreter. When attempting to install an interpreter package through an intention action, you might receive the following error message:
    System Interpreter warning message
    As prompted, consider using a virtual environment for your project. Click OK to complete the task.

    See Configure a system interpreter for more details.

    In the left-hand pane of the Add Python Interpreter dialog, click SSH Interpreter. In the right-hand pane select New server configuration, then specify server information (host, port, and username).
    adding an interpreter via SSH
    Alternatively, you can select Existing server configuration and choose any available deployment configuration from the list.
    Existing SSH configuration
    If needed, click The Browse button to review the Connection settings, Mappings, and Excluded paths for the selected deployment configuration. Click Next to continue configuring an interpreter.

    In the next dialog window, provide the authentication details to connect to the target server.

    specifying authentication details

    Select Password or Key pair (OpenSSL or PuTTY) and enter your password or passphrase.

    Click Next to proceed with the final configuration step.

    In the next dialog window, verify the path to the desired Python interpreted. You can accept default, or specify a different one. You have to configure the path mappings between your local project and the server. To do that, click The Browse button next to the Sync folders field and enter the path to the local project folder and the path to the folder on the remote server.

    Setting SSH mappings

    You can also select the lowest checkbox to enable automatic upload of the local changes to the remote server.

    See Configure a remote interpreter using SSH for more details.

    In the left-hand pane of the Add Python Interpreter dialog, click Vagrant:
    Add an interpreter

    Click the browse button The Browse button next to the field Vagrant instance folder, and specify the desired Vagrant instance folder.

    This results in showing the link to Vagrant host URL.

    The Python interpreter path field displays the path to the desired Python executable. You can accept default, or specify a different one. Click OK. The configured remote interpreter is added to the list.

    See Configure a remote interpreter using Vagrant for more details.

    In the left-hand pane of the dialog, click WSL.

    Adding a WSL interpreter

    Select the Linux distribution and specify the path to the python executable in the selected Linux distribution.

    See Configure a remote interpreter using WSL for more details.

    In the dialog that opens, select the Docker option, from the drop-down lists select the Docker server (if the server is missing, click New...), and specify the image name.

    Python interpreter path should have the default value:

    Choose a docker

    Click OK to complete the task.

    See Configure a remote interpreter using Docker for more details.

    In the dialog that opens, select the Docker Compose option, from the drop-down lists select the Docker server, Docker Compose service (here web), configuration file (here docker-compose.yml)and image name (here python).

    Why we've chosen web? This choice is explained by the fact, that after configuring a Docker-Compose-based interpreter, we'll be able to create regular run configurations that will alter the behavior of the container we selected. Therefore, if we want to debug the code in a container, that's the one we should select here. All other containers in the compose file will always be started together with this one, but you won't be able to affect their behavior from PyCharm - they'll always behave as if you started them with the command docker-compose up from the command line.

    Next, wait while PyCharm starts your Docker-Compose configuration to scan and index:

    Configure remote Python interpreter

    Click OK to complete the task.

    See Configure a remote interpreter using Docker Compose 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 an existing project interpreter

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

Changing the project interpreter using the Python Interpreter widget

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

Project interpreter widget

Changing the project interpreter in the project settings

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), select Project <project name> | Project Interpreter.

  2. Expand the list of the available interpreters and click the Show All link. Alternatively, click the The Configure project interpreter icon and select Show All.

  3. Select the target interpreter.

    View interpreters

    When PyCharm stops supporting any of the outdated Python versions, the corresponding project interpreter is marked as unsupported.

  4. Optionally, you can click Edit and type an alternative interpreter name.

    Changing interpreter's name
    The Python interpreter name specified in the Name field, becomes visible in the list of available interpreters. Click OK to apply the changes.

Last modified: 12 April 2019

See Also

Concepts: