Configure a Python 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.

   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. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

3. Select Add Local Interpreter.

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

   

5. In the Interpreter drop-down, select one of the Python interpreters that have been installed in your system, or click and in the Select Python Interpreter dialog that opens, choose the desired 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:

   

   As prompted, consider using a virtual environment for your project.

6. Click OK to complete the task.

For more information, refer to Configure a system interpreter.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select Add Local Interpreter.

3. In the left-hand pane of the Add Python Interpreter dialog, select Virtualenv 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 and browse for the location in your file system. The directory for the new virtual environment should be empty.

   • Choose the base interpreter from the list, or click and find the 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.

   Existing virtual environment

   • Choose the desired interpreter from the list.

   • If the desired interpreter is not on the list, click , 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, refer to Configure a virtual 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.

   For more information, refer to the installation instructions.

2. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

3. Select Add Local Interpreter.

4. In the left-hand pane of the Add Python Interpreter dialog, select 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

   • Select the Python version from the list.

   • Normally, PyCharm will detect conda installation.

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

   • Specify the environment name.

   Existing conda environment

   • Select the environment from the list.

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

6. Click OK to complete the task.

For more information, refer to Configure a conda virtual environment.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select Add Local Interpreter.

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

   

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

5. If your project contains Pipfile, you can choose whether you want to install the packages listed in it by enabling or disabling the Install packages from Pipfile checkbox. By default, the checkbox is enabled.

6. 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 specify it in the dialog.

7. Click OK to complete the task.

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, refer to Configure a pipenv environment.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select Add Local Interpreter.

3. In the left-hand pane of the Add Python Interpreter dialog, select 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 and find the Python executable in your file system.

   • If your project contains pyproject.toml, you can choose whether you want to install the packages listed in it by enabling or disabling the Install packages from pyproject.toml checkbox. By default, the checkbox is enabled.

   • If PyCharm doesn't detect the poetry executable, specify the following path in the dialog, 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, click , 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, refer to Configure a Poetry environment.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select On WSL.

3. Wait until PyCharm detects Linux on your machine and completes introspection. Click Next to proceed:

   

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

   

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

   For virtual and conda 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.

Once done, the new interpreter will be added to your project, and the default mnt mappings will be set.

For more information, refer to Configure an interpreter using WSL.

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

   • 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 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

   For more information, refer to Vagrant documentation.

4. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

5. Select On Vagrant.

6. Specify the path to the Vagrant instance folder in Vagrant Instance Folder.

   Wait until you see a link in Vagrant Host URL.

7. In the New Target: Vagrant dialog, click the browse icon next to the Vagrant Instance Folder field, and specify the desired Vagrant instance folder.

   This results in showing the link to Vagrant Host URL.

   

8. In the next field, PyCharm will display the path to the Python executable. Press "Next" to proceed.

   

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

   

   Clik Create to complete the task.

For more information, refer to Configure an interpreter using Vagrant.

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

2. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

3. Select On SSH.

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

   

   Alternatively, you can select Existing and choose any available SSH configuration from the list. To create a new SSH configuration, follow the steps below:

   Creating an SSH configuration

   • Click next to the list of configurations:

     

   • Click , disable the Visible only for this project checkbox, and fill in the required fields:

     

   • Once done, the newly created SSH configuration will appear in the list of available configurations. It will also become available in the SSH Deployment Configurations settings. Click Next to proceed:

     

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

   

   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. Wait until PyCharm completes the introspection of the SSH server.

   

7. In the next dialog, select a type of Python environment to configure on the SSH server.

   

   You can create a new virtual environment or сonda environment, select an existing one, or use a system interpreter.

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

   • If you need to execute your Python code on the SSH server as a sudo user, enable the Execute code with root privileges via sudo checkbox.

   • 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 the interpreter.

For more information, refer to Configure an interpreter using SSH.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select On Docker.

3. Select an existing Docker configuration in the Docker server dropdown.

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

   Create a Docker configuration

   Click 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, refer to Docker connection settings.

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

   

   For more information about mapping local paths to the virtual machine running the Docker daemon when using Docker on Windows or macOS, refer to 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.

4. The following actions depend on whether you want to pull a pre-built image from a Docker registry or to build an image locally from a Dockerfile.

   Pull a Docker image

   Select Pull or use existing and specify the tag of the desired image in the Image tag field.

   

   Build a Docker image

   Select Build and change the default values in the Dockerfile and Context folder fields if necessary.

   

   If required, expand the Optional section and specify the following:

   Image tag	Specify an optional name and tag for the built image. This can be helpful for referring to the image in the future. If you leave the field blank, the image will have only a random unique identifier.
   Build options	Set supported docker build options. For example, you can specify metadata for the built image with the --label option.
   Build args	Specify the values for build-time variables that can be accessed like regular environment variables during the build process but do not persist in the intermediate or final images. This is similar to using the --build-args option with the docker build command. These variables must be defined in the Dockerfile with the ARG instruction. For example, you can define a variable for the version of the base image that you are going to use: ARG PY_VERSION=latest FROM python:$PY_VERSION The PY_VERSION variable in this case will default to latest and the Dockerfile will produce an image with the latest available version of Python, unless you redefine it as a build-time argument. If you set, PY_VERSION=3.10, Docker will pull python:3.10 instead, which will run a container with Python version 3.10. Redefining the PY_VERSION argument is similar to setting the following command-line option: --build-arg PY_VERSION=3.10 You can provide several arguments separated by spaces.

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

   

6. Next, select an interpreter to use in the Docker container. You can choose any virtualenv or conda environment that is already configured in the container or select a system interpreter.

   

7. Click OK.

   The configured remote interpreter is added to the list.

For more information, refer to Configure an interpreter using Docker.

1. Do one of the following:

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

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

   • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

2. Select On Docker Compose.

3. Select Docker configuration in the Server dropdown.

4. Specify the docker-compose.yml file in Configuration files and select the service.

   

   Optionally, specify environment variables and edit the Compose project name.

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

   

6. Select an interpreter to use in the container. You can choose any virtualenv or conda environment that is already configured in the container, or select a system interpreter.

   

7. Click OK.

   The configured remote interpreter is added to the list.

For more information, refer to Configure an interpreter using Docker Compose.