IntelliJ IDEA 2023.1 Help

Configure a Python SDK

To develop Python scripts in IntelliJ IDEA, download and install Python and configure at least one Python SDK. A Python SDK can be specified as a Python interpreter for Python project.

IntelliJ IDEA supports:

To view the list of available SDKs, choose File | Project Structure from the main menu Control+Alt+Shift+S. Python SDKs can be configured on the following levels:

Show available Python SDKs
Change a Python SDK
Manage Python SDK modules

To easily tell them from each other, enter different names in the Name field. See SDKs for more information about SDK configuration.

To add a Python SDK, you must configure a Python interpreter. Regardless of the level, you can configure a local or a remote Python interpreter.

Configuring local Python interpreters

To configure a local Python interpreter, adhere to one of the following procedures:

Configure a system interpreter

  1. Ensure that you have downloaded and installed Python on your computer.

    Installing Python on Windows from Microsoft Store

    If you are on Windows, you can download Python from the Microsoft Store and install it as a Python interpreter. Once the Python application is downloaded from the Microsoft Store, it becomes available in the list of the Python executables.

    Python interpreter installed from the Windows store
    Note that interpreters added from the Microsoft Store installations come with some limitations. Because of restrictions on Microsoft Store apps, Python scripts may not have full write access to shared locations such as TEMP and the registry.

  2. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  3. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  4. In the left-hand pane of the Add Python Interpreter dialog, select System Interpreter.

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

    Selecting the Python executable

    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.

  6. Click OK to complete the task.

For more information, see Configure a system interpreter.

Create a virtualenv environment

  1. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  2. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  3. In the left-hand pane of the Add Python Interpreter dialog, select Virtualenv Environment.

    Creating a virtual environment
  4. The following actions depend on whether you want to create a new virtual environment or to use an existing one.

    New virtual environment
    • Specify the location of the new virtual environment in the Location field, or click Virtual environment location and browse for the desired location in your file system. The directory for the new virtual environment should be empty.

    • Choose the base interpreter from the list, or click Choose the base interpreter and find the desired Python executable in your file system.

    • Select the Inherit global site-packages checkbox if you want 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 IntelliJ IDEA.

    Existing virtual environment
    • Choose the desired interpreter from the list.

    • If the desired interpreter is not on the list, click App general ellipsis, and then browse for the desired Python executable (for example, venv/bin/python on macOS or venv\Scripts\python.exe on Windows).

    The selected virtual environment will be reused for the current project.

  5. Click OK to complete the task.

For more information, see Configure a virtual environment.

Create a conda environment

  1. Ensure that Anaconda or Miniconda is downloaded and installed on your computer, and you're aware of a path to its executable file.

    Refer to the installation instructions for more details.

  2. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  3. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  4. In the left-hand pane of the Add Python Interpreter dialog, select Conda Environment.

    New Conda environment
  5. The following actions depend on whether you want to create a new conda environment or to use an existing one.

    New conda environment
    • Specify the location of the new conda environment in the Location field, or click Conda environment location and browse for the desired location in your file system. The directory for the new conda environment should be empty.

    • Select the Python version from the list.

    • Normally, IntelliJ IDEA will detect conda installation.

      Otherwise, specify the location of the conda executable, or click Conda executable location to browse for it.

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

    Existing conda environment
    • Choose the desired environment from the list.

    • If the desired interpreter is not on the list, clickApp general ellipsis, and then browse for the Python executable within the previously configured conda environment.

    • If necessary, specify the location of the conda executable, or click App resharper ide folder opened to browse for it.

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

    The selected conda environment will be reused for the current project.

  6. Click OK to complete the task.

For more information, see Configure a conda virtual environment.

Create a pipenv environment

  1. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  2. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  3. In the left-hand pane of the Add Python Interpreter dialog, select Pipenv Environment.

    Adding a Pipenv environment
  4. Choose the base interpreter from the list, or click Choose the base interpreter and find the desired Python executable in your file system.

  5. If you have added the base 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.

    If the pipenv executable is not found, follow the pipenv installation procedure to discover the executable path, and then paste it in the Pipenv executable field.

  6. Click OK to complete the task.

Once all the steps are done, the new pipenv environment is set for your project and the packages listed in the Pipfile are installed.

If you open a project with a Pipfile file added but no any interpreter configured, IntelliJ IDEA offers you to use Pipenv environment.

Pipenv inspection

If you select this option, IntelliJ IDEA sets pipenv for you automatically. Alternatively, you can click Configure Python interpreter to follow the standard workflow.

Similarly, when you open a project with a Pipfile file in IntelliJ IDEA for the very first time, for example, by checking it out from the Version Control, the Pipenv virtual environment will be configured automatically.

When you have set the Pipenv virtual environment as a Python interpreter, all available packages are added from the source defined in Pipfile . The packages are installed, removed, and updated in the list of the packages through pipenv rather than through pip.

For more information, see Configure a Pipenv environment.

Create a Poetry environment

  1. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  2. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  3. In the left-hand pane of the Add Python Interpreter dialog, select Poetry Environment.

    creating a poetry environment
  4. The following actions depend on whether you want to create a new Poetry environment or to use an existing one.

    New Poetry environment
    • Select Poetry Environment.

    • Choose the base interpreter from the list, or click Choose the base interpreter and find the desired Python executable in your file system.

    • If IntelliJ IDEA 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
    Existing Poetry environment
    • Make sure that the project directory contains a pyproject.toml file.

    • Select Existing environment. Then expand the Interpreter list and choose the desired interpreter.

    • If the desired interpreter is not on the list, clickApp general ellipsis, and then browse for the Python executable within the previously configured Poetry environment.

    The selected Poetry environment will be reused for the current project.

  5. Click OK to complete the task.

For more information, see Configure a Poetry environment.

Configuring remote Python interpreters

To configure a remote Python interpreter:

Configure a WSL interpreter

  1. Click the Windows button in the lower-left corner of the screen and start typing System Information. To ensure that your system works well with WSL, upgrade your Windows to the latest available version.

  2. Install the Windows Subsystem for Linux and initialize your Linux distribution as described in the WSL Installation Guide.

  3. If your Linux distribution doesn't come with rsync, you need to install it:

    sudo apt install rsync

    sudo pacman -S rsync

  4. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  5. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  6. In the left-hand pane of the Add Python Interpreter dialog, select WSL.

  7. Select the Linux distribution with the required Python interpreter.

  8. In Python interpreter path field, specify the path to the Python executable. You can accept the default, type in a different path, or click the Browse button to browse.

    Add a remote interpreter using WSL
  9. Click OK.

    The configured remote interpreter is added to the list.

Configure an interpreter using Vagrant

  1. Ensure that the following prerequisites are met (outside of IntelliJ IDEA):

    • One of supported Vagrant providers is installed on your computer.

    • Vagrant is installed on your computer, and all the necessary infrastructure is created.

    • The parent folders of the following executable files have been added to the system PATH variable:

      • vagrant.bat or vagrant from your Vagrant installation. This should be done automatically by the installer.

      • VBoxManage.exe or VBoxManage from your Oracle's VirtualBox installation.

    • The required virtual boxes are created.

  2. Make sure that the Vagrant plugin is installed and enabled.

  3. Ensure that you have properly initiated and started Vagrant. Basically, you need to open the Terminal window and execute the following commands:

    $ vagrant init ubuntu/trusty64

    and

    $ vagrant up

    See Vagrant documentation for more information.

  4. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  5. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  6. In the left-hand pane of the Add Python Interpreter dialog, select Vagrant.

  7. In Python interpreter path field, specify the path to the Python executable. You can accept the default, type in a different path, or click the Browse button to browse.

    Add a remote interpreter using Vagrant
  8. Click OK.

    The configured remote interpreter is added to the list.

Configure an interpreter using SSH

  1. Ensure that there is an SSH server running on a remote host, since IntelliJ IDEA runs remote interpreters via ssh-sessions.

  2. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  3. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  4. 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 configurations

    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.

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

  6. In the next dialog window, verify the path to the desired Python interpreter. You can accept the 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 checkbox to enable automatic upload of the local changes to the remote server.

  7. Click OK.

    The configured remote interpreter is added to the list.

Configure an interpreter using Docker

  1. Make sure that the following prerequisites are met:

    • Docker is installed, as described in the Docker documentation.

    • You have stable Internet connection, so that IntelliJ IDEA can download and run busybox:latest (the latest version of the BusyBox Docker Official Image). Once you have successfully configured an interpreter using Docker, you can go offline.

    Note that you cannot install any Python packages into Docker-based project interpreters.

  2. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  3. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  4. In the left-hand pane of the Add Python Interpreter dialog, select Docker.

    Adding a Python interpreter using Docker
  5. Select an existing Docker configuration in the Server dropdown.

    Alternatively, click New and perform the following steps to create a new Docker configuration:

    Create a Docker configuration

    Click New to add a Docker configuration and specify how to connect to the Docker daemon.

    The connection settings depend on your Docker version and operating system. For more information, see Docker connection settings.

    The Connection successful message should appear at the bottom of the dialog.

    The Docker connection settings for interpreter

    For more information about mapping local paths to the virtual machine running the Docker daemon when using Docker on Windows or macOS, see Virtual machine path mappings for Windows and macOS hosts. You will not be able to use volumes and bind mounts for directories outside of the mapped local path.

    This table is not available on a Linux host, where Docker runs natively and you can mount any directory to the container.

  6. Specify the image and the path to the Python executable:

    Configuring a Python interpreter using Docker
  7. Click OK.

    The configured remote interpreter is added to the list.

Configure an interpreter using Docker Compose

  1. Make sure that the following prerequisites are met:

    • Docker is installed, as described in the Docker documentation.

    • You have stable Internet connection, so that IntelliJ IDEA can download and run busybox:latest (the latest version of the BusyBox Docker Official Image). Once you have successfully configured an interpreter using Docker, you can go offline.

    Note that you cannot install any Python packages into Docker-based project interpreters.

  2. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  3. In the Project Structure dialog, select SDKs under the Platform Settings section, click Add a new SDK, and choose Add Python SDK from the popup menu.

    Adding a new Python SDK
  4. In the left-hand pane of the Add Python Interpreter dialog, select Docker Compose.

    Adding a Python interpreter using Docker Compose
  5. Select an existing Docker configuration in the Server dropdown.

    Alternatively, click New and perform the following steps to create a new Docker configuration:

    Create a Docker configuration

    Click New to add a Docker configuration and specify how to connect to the Docker daemon.

    The connection settings depend on your Docker version and operating system. For more information, see Docker connection settings.

    The Connection successful message should appear at the bottom of the dialog.

    The Docker connection settings for interpreter

    For more information about mapping local paths to the virtual machine running the Docker daemon when using Docker on Windows or macOS, see Virtual machine path mappings for Windows and macOS hosts. You will not be able to use volumes and bind mounts for directories outside of the mapped local path.

    This table is not available on a Linux host, where Docker runs natively and you can mount any directory to the container.

  6. In Configuration files, specify the docker-compose.yml file. Also select the service.

    Configuring a Python interpreter using Docker Compose

    Optionally, specify environment variables.

  7. Finally, specify the path to the Python executable:

    Configuring a Python interpreter using Docker Compose
  8. Click OK.

    The configured remote interpreter is added to the list.

For more details about remote Python interpreters, refer to Configure remote Python interpreters.

Removing Python interpreters

If you no longer need a Python interpreter for a project, you can remove it from the project settings.

  1. Navigate to File | Project Structure or press Control+Alt+Shift+S.

  2. In the Project Structure dialog, click SDKs node under Platform Settings.

  3. Choose the interpreter that you want to remove and click Remove Interpreter.

    Remove a Python interpreter

For any of the configured Python interpreters (but Docker-based), you can:

Last modified: 20 February 2023