PyCharm 2023.1 Help

Configure a virtual environment

PyCharm makes it possible to use the virtualenv tool to create a project-specific isolated virtual environment. The main purpose of virtual environments is to manage settings and dependencies of a particular project regardless of other Python projects. virtualenv tool comes bundled with PyCharm, so the user doesn't need to install it.

Create a virtualenv environment

  1. Do one of the following:

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

    • Press Control+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.

    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.

    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.

You can create as many virtual environments as required. To easily tell them from each other, use different names.

Use an existing interpreter

  1. Press Control+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. Alternatively, click the The Configure project interpreter icon and select Show All.

    Show all available interpreters

    Virtual environments are marked with Virtual environment.

  3. Select the target environment from the list and click OK to confirm your choice.

    Select a virtual environment

PyCharm can create a virtual environment for your project based on the project requirements.

Create a virtual environment using the project requirements

  1. Open any directory with your source files that contains the requirements.txt or setup.py file: select File | Open from the main menu and choose the directory.

  2. If no virtual environment has been created for this project, PyCharm suggests creating it:

    Create a virtual environment using the requirements.txt file
  3. Keep the suggested options, or specify the environment location or base Python interpreter. Click OK to complete the task.

Once you click OK, PyCharm creates an environment and installs all the required packages. On the completion, see the notification popup:

The environment is created

Note that if you ignore a suggestion to create a virtual environment, PyCharm won't create a Python interperter for your project. So, any time when you open a .py file, you'll see the warning with the options for configuring a project interpreter:

Warning with options for configuring a project interpreter

This approach is particularly helpful when you want to upgrade a version of Python your environment is based on, for example, from 3.5 to 3.9. You can specify a new base interpreter and use requirements.txt to ensure all the needed packages are installed.

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

Once you have create a new virtual environment, you can reuse it for your other projects. Learn more how to setup an existing environment as a Python interpreter.

Last modified: 15 March 2023