Making a virtual environment in PyCharm happens mostly in the New Project dialog. Open File > New Project, choose Project venv, and click Create. PyCharm builds the venv in a .venv folder inside the project and sets it as the project interpreter.
One thing changed recently. As of PyCharm 2025.3 (released December 2025), the New Project wizard suggests uv as the default environment manager whenever it detects uv on the machine, according to JetBrains’ release notes. Tutorials written before then don’t mention it.
Each venv has its own Python binary and its own set of installed packages, per PEP 405. That keeps dependency versions apart from the system Python and from every other project on the machine.
How to Create a Virtual Environment in PyCharm for a New Project
Enter the project location, then pick Project venv. PyCharm builds a virtualenv from whichever Python version you select, inside the project folder.
The wizard also chooses a default environment tool for you, and since 2025.3 that means uv when uv is installed (JetBrains’ release notes again). If you picked venv, Conda or Poetry in the past, PyCharm remembers that choice. Everyone else sees uv preselected, so glance at the option before you click Create.
- Open File > New Project, or click New Project on the Welcome screen.
- Enter the project location.
- Select Project venv.
- Check the Python version the environment will use.
- Click Create.
- Look at the Python Interpreter widget in the status bar to confirm the new environment is active.
The rest of the project setup has its own walkthrough on creating a new project in PyCharm.
Choosing the Base Interpreter
The base interpreter decides the Python version of the environment. Per PEP 405, each environment gets its own Python binary and shares the standard library with the base install.
The dropdown lists the Python installations PyCharm detected. If yours lives somewhere unusual, hit Browse and point it at the python or python.exe file. And if PyCharm finds nothing at all, the New Project dialog on Windows and macOS can download and install a Python version for you. On Linux you install Python yourself first.
Pick the newest Python your dependencies support. Want a different version later? That means a new environment on a different base interpreter.
Choosing the Environment Location
Python’s venv documentation names two conventions. One is a .venv or venv folder inside the project, the other a shared container directory such as ~/.virtualenvs.
The Project venv option has no Location field. It always creates the environment in .venv in the project root. The Location field shows up under Virtualenv in the Add Local Interpreter dialog, and under Custom environment in the New Project dialog. JetBrains’ help says the target directory should be empty.
Inside the project, the environment is easy to find and stays with the code. Outside it, you get a cleaner tree and one place for many environments, at the price of having to remember where they live.
For a single project, keep it inside. Project venv already does.
How to Add a Virtual Environment to an Existing Project
The Python Interpreter widget in the status bar is the usual starting point. Settings, Python, Interpreter, and the Add Interpreter link lead to the same dialog. The wider process of adding a Python interpreter in PyCharm has its own guide.
- Click the Python Interpreter widget in the status bar and choose Add New Interpreter.
- Select Add Local Interpreter.
- Choose Virtualenv from the list of environment types to create a new environment, or Python to reuse an existing one.
- For a new environment, select the base interpreter and set the Location (an empty directory).
- Tick the optional checkboxes you need (see below).
- Click OK.
Reusing an existing environment just points the current project at the selected virtualenv. Ticking Inherit packages from base interpreter adds every package installed in the global Python to the new environment, which undoes part of the reason you made an isolated one. I leave it off almost every time. Make available to all projects lets you reuse the environment when you configure interpreters in other projects.
In JetBrains’ 2023.2, 2024.3 and 2025.1 help pages, the inherit option is called Inherit global site-packages. The 2026.1 help renames it, so older tutorials describe a label you will not see.
Projects that contain a requirements.txt (or a setup.py) but no interpreter get a prompt, Create a virtual environment using requirements.txt. Accepting it builds the environment and installs the listed packages.
Ignore the prompt and PyCharm creates no interpreter for the project, per JetBrains’ 2026.2 help.
Which Environment Type Should You Pick in PyCharm?
Project venv fits most projects. If the project already runs on uv, stay with uv. Poetry earns its place when a pyproject.toml with a lock file is already in the repo, and Conda only when you actually need conda packages.
| Type | What PyCharm creates | Install first | Best fit |
|---|---|---|---|
| Project venv | virtualenv from the selected Python, in the project folder | Nothing beyond Python | Most single-project work |
| uv | uv environment plus a generated pyproject.toml | uv | Projects already managed with uv |
| Conda | Base or named conda environment | Conda | Projects that need conda packages |
| Poetry | Poetry environment tied to pyproject.toml | Poetry (PyCharm can install it via pip) | Projects with an existing pyproject.toml |
In the Python Developers Survey 2024 from the PSF and JetBrains, venv led environment isolation at 62%, with uv at 11% in its first year on the list.
About a year after that survey was fielded, PyCharm 2025.3 made uv the suggested default whenever it detects uv. So the IDE default and the most-used tool now differ. For a single project with a short package list, that gap changes nothing.
Poetry gets some hand-holding inside the IDE. PyCharm offers to install Poetry through pip when it finds none, and prompts for poetry lock or poetry update after pyproject.toml edits. Pipenv is handled in a similar way. PyCharm autodetects the pipenv executable when it can, offers Install pipenv via pip when it cannot, and installs packages through pipenv instead of pip.
A separate breakdown compares venv, Conda and Poetry as standalone tools outside the IDE.
PyCharm 2025.3 moved Community users to one unified PyCharm and ended the separate Community installer (JetBrains, December 2025). The unified product itself debuted in 2025.1, and 2025.2 was the last standalone Community release. The old split between Community and Professional now lives inside a single app as a free core plus a Pro license.
JetBrains’ editions matrix is the reference for which features need Pro. Per JetBrains’ interpreter help, the local environment types (virtualenv, Pipenv, Poetry, uv, Hatch and Conda) are part of the core, while remote interpreters over SSH, Docker, Docker Compose or WSL need Pro.
How to Install Packages Into the Virtual Environment
Open the Python Packages tool window, search for the package name, and click Install. PyCharm uses pip by default and installs into the interpreter currently selected for the project.
The tool window is on by default. If it is hidden, open it from View > Tool Windows > Python Packages.
It lists installed packages and the packages available on PyPI. When the current interpreter is a conda environment, it also shows the conda repository, per JetBrains’ 2026.2 help.
The interpreter settings work too, thanks to an install button on the package toolbar. Or add a requirements.txt to the project and accept the install prompt. The Advanced Package Install button next to the tool window’s search bar covers installs from a version control system or from disk. A separate guide goes through installing packages in PyCharm in more detail.
Python Developers Survey 2024 found that 59% of respondents store application dependencies in requirements.txt, ahead of pyproject.toml at 36%.
Add the file to the project and PyCharm prompts to install every package it lists.
A common error is running pip in a terminal where the environment is not activated. The package then goes into whichever Python comes first on PATH, not into the project environment. Python’s venv documentation explains that activation works by putting the environment’s directory first on PATH. Installing through the tool window avoids the problem.
Check which interpreter the tool window shows before you install. The packages it lists belong to that interpreter only, so a package missing there is not in this environment.
How PyCharm Activates the Environment in the Terminal and Run Configurations
New Terminal tabs activate the project environment on their own when the Activate virtualenv option is on under Settings > Tools > Terminal. Run configurations work differently, because each one names the interpreter it runs with.
JetBrains’ terminal settings help (2026.2) lists the option under that label and says it is available only with the Python plugin installed. Shell integration sits on the same settings page, and per that help it works for sh, bash, zsh and fish.
The Terminal tool window itself has a short guide on opening a terminal in PyCharm.
If a Terminal opens without the environment name, the option is probably off, so tick Activate virtualenv under Settings > Tools > Terminal. Check the Python Interpreter widget in the status bar as well. It shows which interpreter the project uses, and the Terminal follows it. On Windows, the execution policy can block Activate.ps1, and Python’s venv documentation says the policy can be set for the current user.
Open a fresh Terminal tab after any of these changes. A tab that was already running keeps the state it started with.
Each run configuration carries its own Python Interpreter field, which takes one of the pre-configured interpreters (JetBrains help). Point it at the project environment and the script runs inside it, with no activate step.
Projects managed by uv behave differently. PyCharm 2025.3 uses uv run as the default command for their run configurations, according to the release notes.
Running scripts through those configurations has its own walkthrough on running code in PyCharm.
Why PyCharm Fails to Create or Detect the Environment
If the build fails at the location you picked, look at the folder first. A non-empty target directory stops it. Most of the other causes are in the table.
| Symptom | Cause | Fix |
|---|---|---|
| Environment build fails at the chosen location | Directory is not empty | Pick an empty folder |
| Invalid environment warning | Python binary missing, or version unsupported | Re-select the base interpreter |
| No interpreter in a fresh project | Interpreter prompt dismissed | Status bar widget, Add New Interpreter |
| “ensurepip is not available” error | venv package not installed on Debian or Ubuntu | Install python3-venv, then recreate |
| Imports resolve to unexpected packages | Another interpreter is active | Switch with the Python Interpreter selector |
On Debian and Ubuntu, the venv bootstrap module (ensurepip) comes in a separate python3-venv package, so creating an environment without it stops with an ensurepip error. The message names the fix itself.
Install the package with sudo apt install python3-venv. Parallel Python versions ship their own packages, such as python3.8-venv on Ubuntu 18.04, so match the package to the version. Ubuntu’s Launchpad tracker (bug 1851684) records that python3.8-venv on 18.04 could still fail with the same ensurepip message because it lacked a python3-distutils dependency. Once the package is in, recreate the environment from scratch.
The Invalid environment case has a version angle. JetBrains marks an interpreter as unsupported once PyCharm drops support for that outdated Python version, per the Python interpreters help.
Build a new environment on a newer base interpreter then, as covered in a guide to changing the Python version in PyCharm.
If the base interpreter itself is gone, the environment has no standard library left to share with it (PEP 405), so rebuild it.
How to Delete, Recreate, and Exclude the Environment From Git
Remove the interpreter in Settings, delete the folder from disk, build a replacement, and add the folder to .gitignore. Python’s venv documentation describes an environment as disposable, simple to delete and recreate from scratch.
To remove it from PyCharm, open Settings > Python > Interpreter (or click the Python Interpreter selector and choose Interpreter Settings), expand the interpreter list and click Show All, select the interpreter, and click Remove Interpreter. JetBrains’ help describes this as removing it from the project settings.
The folder stays where it is until you delete it yourself. A separate piece covers how to delete a venv.
Check for sharing before you delete. An environment created with Make available to all projects can sit in other projects’ interpreter lists, so deleting the folder breaks every project that points to it.
JetBrains’ help words this setting two ways. The Add dialog (2024.3 through 2026.2 help) says Make available to all projects. The 2026.2 interpreter-editing help describes the inverse, Associate this virtual environment with the current project, which makes the interpreter available only in the current project.
To recreate it, build the replacement through Add Local Interpreter, then install from requirements.txt. Python’s documentation tells users to keep a simple way of rebuilding an environment for exactly this reason.
Environments are non-portable because script shebang lines hold absolute paths to the interpreter. CPython added that warning to the venv docs in October 2022 (gh-88452), and it covers moved or renamed project folders too. Recreate the environment at the new location and delete the old one.
Python’s venv documentation also lists environments as not checked into source control. GitHub’s Python.gitignore template carries the usual folder names, which are .venv, venv/, env/ and ENV/.
Add the matching lines to the project’s gitignore file before the first commit. Since Python 3.13, venv also writes a .gitignore inside the environments it creates by default, but an explicit line in the project’s own file covers environments made other ways.
The .idea folder follows different rules. JetBrains’ sharing project settings help (PyCharm 2026.2) says to keep .idea/workspace.xml and .idea/usage.statistics.xml out of version control, and notes that interpreter display names can be portable because .idea/misc.xml stores the name (project-jdk-name), not the path.
A teammate who clones the repository gets the name but not the environment, so they build their own from requirements.txt.
Virtual Environment in PyCharm FAQ
Does PyCharm use venv or virtualenv for a new environment?
JetBrains’ help through the 2025.1 release says PyCharm uses the built-in venv module on Python 3.3 and later, even though the dialog says Virtualenv. The 2026.1 and 2026.2 help pages no longer repeat that line and describe the virtualenv tool as bundled with PyCharm, so treat the name in the dialog as a label rather than a guarantee of which tool runs underneath.
The two share a history. PEP 405 added venv to the standard library, building on the third-party virtualenv tool.
What is the pyvenv.cfg file inside the environment folder?
Python looks for this file to decide whether a folder is a virtual environment at all. Its home key points to the Python installation that created the environment.
A second key, include-system-site-packages, records whether the environment sees the base interpreter’s packages.
How can I tell which Python an existing environment is built on?
Open pyvenv.cfg in the environment folder and read the home key, which names the base installation.
The environment’s own binary is a copy or symlink of the one that created it, per Python’s venv documentation. The Python Interpreter widget in the status bar names the interpreter the project currently uses.
Can I change the Python version of an existing environment?
Not to a different version, no. Create a new environment on a base interpreter with the version you want, then reinstall from requirements.txt.
The venv –upgrade option covers one narrow case. It updates an environment after its base Python was upgraded in place.
What a Teammate Needs to Rebuild Your Environment
A virtual environment in PyCharm rebuilds on another machine from a single file, the output of pip freeze saved as requirements.txt. Run the command with the environment’s own interpreter so the list reflects that environment only.
pip freeze pins the installed packages, transitive dependencies included, but it leaves out bootstrap tools (pip on Python 3.12 and later; pip, setuptools and wheel on 3.11 and earlier) unless you pass –all. It also computes no lockfile or solver result (pip documentation).
A project created with uv, the 2025.3 wizard default when uv is installed, starts with a generated pyproject.toml rather than requirements.txt, so the file to share follows the manager chosen at creation.
Do the export last.
- Finish installing, then export the pins.
- Write the Python version beside the file.
- Rebuild once in an empty folder.
Once the rebuild works, the project is ready for a repository, and the first step there is connecting PyCharm to GitHub.
- Notepad++ Vulnerability History and How to Stay Safe - October 27, 2026
- What Code-Level Optimisations Technical SEO Specialists Perform - October 27, 2026
- How to Add an AI Support Agent to a SaaS Product: Data, Integration and Guardrails - October 27, 2026
