PyCharm 2022.2 Help

Configure a Python interpreter

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, Poetry, 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

Python interpreters

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:

    Project interpreter selector

Change the Python interpreter in the project settings

  1. Press Ctrl+Alt+S to open the IDE settings and select Project <project name> | Python Interpreter.

  2. Expand the list of the available interpreters and click the Show All link.

    Show all available interpreters
  3. Select the target interpreter.

    View interpreters

    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 the local content with the target server. Mind a notification balloon in the lower-right corner:

Sync local files with the deployment server
You can choose to perform one of the following actions:

  • Auto-upload files to the server

  • Synchronize files and then enable auto-uploading

Modify a Python interpreter

  1. Press Ctrl+Alt+S to open the IDE settings and select Project <project name> | Python Interpreter.

  2. Expand the list of the available interpreters and click the Show All link.

    Show all available interpreters
  3. Select the target interpreter and click Edit.

    Edit icon

    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.

    Edit interpreter settings

Creating a new Python interpreter

To add a new interpreter to the current project:

  1. Do one of the following:

    • Click the Python Interpreter selector and choose Add New Interpreter.

    • Press Ctrl+Alt+S to open the project Settings/Preferences and go to Project: <project name> | Python Interpreter. Click the Add Interpreter link next to the list of the available interpreters.

  2. Choose the interpreter type to add and perform the specific settings. For virtual environments and system interpreters, select Add Local Interpreters. For remote interpreters, select a specific type.

    1. Select Add Local Interpreter from the list of the available interpreter types.

      Adding local interpreters
    2. 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.

      creating a virtual environment

      If New Virtualenv 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 a Python executable in 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).

        Downloading Python when creating a virtual env

      3. 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.

      If you select any of the existing virtual environments from the Interpreter list, it will be reused for the current project.

    3. Click OK to complete the task.

    See Configure a virtual environment for more details.

    1. 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 pipenv executable is autodetected
    2. Click OK to complete the task.

    3. 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.

    1. Select Add Local Interpreter from the list of the available interpreter types.

      Adding local interpreters
    2. In the left-hand pane of the Add Python Interpreter dialog, select Poetry Environment. The following actions depend on whether the virtual environment existed before.

      creating a poetry environment

      If Poetry Environment is selected:

      • Select the base Python interpreter from the list, or click Virtual environment location and find its location in your file system.

      • If PyCharm doesn't detect the poetry executable, specify the following path in the Poetry executable field, replacing jetbrains with your username:

        /Users/jetbrains/Library/Application Support/pypoetry/venv/bin/poetry
        C:\Users\jetbrains\AppData\Roaming\pypoetry\venv\Scripts\poetry.exe
        /home/jetbrains/.local/bin/poetry

      If Existing environment is selected:

      • Expand the Interpreter list and select any of the existing Poetry environments. Alternatively, click Select an interpreter and specify a path to it.

    3. Click OK to complete the task.

    See Configure a Poetry environment for more details.

    1. 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.

      New Conda environment

      If New Virtualenv 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. You're basically looking for a path that you've used when installing Conda on your machine.

      4. Select the Make available to all projects checkbox if you want to reuse this environment when creating Python interpreters in PyCharm.

      If you select any of the existing virtual environments from the Interpreter list, it will be reused for the current project.

    2. Click OK to complete the task.

    See Configure a Conda virtual environment for more details.

    1. Select Add Local Interpreter from the list of the available interpreter types.

      Adding local interpreters
    2. In the left-hand pane of the Add Python Interpreter dialog, select System Interpreter.

      Adding a system interpreter
    3. In the Interpreter field, type the fully-qualified path to the required interpreter executable, or click the Browse button and in the Select Python Interpreter dialog that opens, choose the desired Python executable and click OK.

      When configuring the base interpreter, you need to specify the path to the Python executable. If PyCharm detects no Python on your machine, it provides the following options:

      • Specify a path to the Python executable (in case of non-standard installation)

      • Download and install the latest Python versions from python.org

      • Install Python using the Command-Line Developer Tools (macOS only).

      Downloading Python when creating a new project
      Downloading Python when creating a new project

      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.

    4. Click OK to complete the task.

    See Configure a system interpreter for more details.

    Professional feature: download PyCharm Professional to try.

    1. Select an option to create a new SSH configuration, then specify server information (host, port, and username).

      adding an interpreter via SSH
    2. In the next dialog window, provide the authentication details to connect to the target server.

      specifying authentication details

      Select Password or Key pair (OpenSSH or PuTTY) and enter your password or passphrase. If Key pair (OpenSSH or PuTTY) is selected, specify:

      • Private key: location of the file with a private key

      • Passphrase: similar to a password, it serves to encrypt the private key.

      Click Next to proceed.

    3. Wait until PyCharm completes the introspection of the SSH server.

      SSH server introspection
    4. In the next dialog, you can select a type of Python environment to configure on the SSH server.

      Selecting a Python environment

      You can select a new or existing venv or use a System interpreter.

      You can configure the path mappings between your local project and the server. To do that, click the Browse icon in the Sync folders field and enter the path to the local project folder and the path to the folder on the remote server.

      Click Create to complete adding an interpreter.

    See Configure an interpreter using SSH for more details.

    Professional feature: download PyCharm Professional to try.

    1. Select On Vagrant:

      Add a Vagrant interpreter
    2. In the New Target: Vagrant dialog, click the browse icon the Browse button next to the Vagrant Instance Folder field, and specify the desired Vagrant instance folder.

      This results in showing the link to Vagrant Host URL.

      Specifying the Vagrant instance folder
    3. In the next field, PyCharm will display the path to the Python executable. Press "Next" to proceed.

      Python executable is discovered
    4. You can create a virtual environment (venv or Conda) or use a system Python interpreter for the target Vagrant instance. Note that virtual environment must be configured and available in the specified Vagrant instance folder. Otherwise, the corresponding lists will be empty.

      Virtual environment on a target Vagrant instance

      Press Create to complete the task.

    See Configure an interpreter using Vagrant for more details.

    Professional feature: download PyCharm Professional to try.

    1. Select On WSL from the list of available interpreter types:

      Add a WSL interpreter
    2. Wait until PyCharm detects Linux on your machine and completes introspection. Press Next to proceed:

      Detecting Linux
    3. In the left-hand pane of the dialog, select the type of the WSL interpreter you want to create: Virtual Environment or System Interpreter.

      New WSL interpreter

      For a system interpreter, just provide the path to the Python executable in the selected Linux distribution.

      For virtual environments, you can provide a path to a Python executable of an existing environment in the selected Linux distribution or create a new environment based on the specified Python.

    See Configure an interpreter using WSL for more details.

    Professional feature: download PyCharm Professional to try.

    1. Select On Docker from the list of the available interpreter types.

      Adding Docker-based interpreters
    2. In the New Target: Docker dialog, select Pull to pull pre-built images from a Docker registry, and specify python:latest in the Image tag field. Alternatively, you can configure PyCharm to build images locally from a Dockerfile.

      Creating a new Docker target

      Optionally, specify the docker build options.

    3. Wait for PyCharm to connect to the Docker daemon and complete the container introspection.

      Docker container introspection is completed
    4. Next, select an interpreter to use in the Docker container. You can select any virtual environment that is already configured in the container or select a system interpreter.

      Selecting a system interpreter for a Docker target

    Click OK to complete the task.

    See Configure an interpreter using Docker for more details.

    Professional feature: download PyCharm Professional to try.

    1. Select On Docker Compose from the list of the available interpreter types.

      Adding Docker Compose-based interpreters
    2. In the New Target: Docker dialog, specify the docker server and the docker-compose.yml file. Also select the service.

      Creating a new Docker Compose target

      Optionally, specify environment variables.

    3. Wait until PyCharm creates and configures a new target:

      Configuring
                                    a Docker Compose target
    4. Next, select an interpreter to use in the container. You can select any virtual environment that is already configured in the container or select a system interpreter.

      Selecting a system interpreter for a Docker target

    Click OK to complete the task.

    See Configure an 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 the default interpreter

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

  1. 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).

  2. Select Python Interpreter settings. Then either choose an existing interpreter from the Python interpreter list of click New interpreter 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.

Managing packages

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 New version is available 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:

See the following video tutorial for additional information:

Last modified: 06 September 2022