Installing Python Packages in PyCharm: The Complete Guide

Tools · Published 2026-10-24

A plain taped cardboard box on a weathered wooden table — A taped cardboard parcel on a wooden table.

In PyCharm, packages are installed into the project's interpreter, not into the IDE. Use the Python Packages tool window, the package list under Settings › Project › Python Interpreter, or python -m pip install in PyCharm's terminal; all three work as long as they target the same interpreter your code runs with.

First, know which interpreter you are using

Nearly every "I installed it but PyCharm can't find it" problem comes down to the package going into one Python and the code running in another. Check the interpreter before installing anything:

The status bar (bottom right in PyCharm 2023.x and later) shows the current interpreter, for example Python 3.12 (myproject). Click it to switch or add one.
Settings (PyCharm › Settings on macOS) › Project: <name> › Python Interpreter shows its full path and the packages installed in it.

JetBrains documents the dialogs in Configure a Python interpreter. Menu labels move slightly between releases, but the concept is stable.

Virtualenv, conda or system interpreter?

Interpreter type	Good for	Watch out for
Virtualenv / venv (PyCharm's default for new projects)	Most projects; one isolated environment per project, works with `requirements.txt`	Inherits the standard library of its base Python, including whether tkinter is present
Conda environment	Scientific stacks and packages with heavy native dependencies (GDAL, dlib, CUDA builds)	Mixing `conda install` and `pip install` in one env; prefer conda packages where they exist, pip for the rest
System interpreter	Quick scripts	Needs admin rights, can break OS tools; many Linux distributions block `pip install` there entirely ("externally-managed-environment")

Poetry, Pipenv and uv environments are also supported as interpreter types in recent PyCharm versions; the principle is the same.

Method 1: the Python Packages tool window

Open it from View › Tool Windows › Python Packages. It lists the packages in the current interpreter and has a search box that queries PyPI (and conda channels for conda interpreters). Select a result, optionally choose a version from the drop-down, and click Install. Installed packages show their version and can be upgraded or removed from the same panel. Because it always uses the project interpreter, this is the safest option for beginners.

Method 2: Settings › Python Interpreter

The interpreter settings page shows a table of installed packages with their current and latest versions. The + button opens a package search, − uninstalls, and the upgrade arrow updates a package. It is convenient when you are already in Settings switching interpreters, and it is the quickest way to see at a glance what an environment contains.

Method 3: pip in PyCharm's terminal

PyCharm's built-in terminal activates the project's virtual environment automatically (controlled by the "Activate virtualenv" option in the terminal settings), so pip usually targets the right place. Still, prefer:

python -m pip install requests
python -m pip install "requests>=2.31,<3"
python -m pip list --outdated

python -m pip runs pip as a module of the exact python you invoke, so the package lands in that interpreter. A bare pip is whichever script comes first on PATH and can belong to a different Python, especially on machines with several versions. On Windows, py -m pip does the same through the launcher. To check, compare python -c "import sys; print(sys.executable)" with the interpreter path in Settings.

Working with requirements.txt

When a project contains requirements.txt, PyCharm inspects it and highlights requirements that are not installed, typically offering a quick-fix or banner to install them. You can always do it explicitly:

python -m pip install -r requirements.txt
python -m pip freeze > requirements.txt   # snapshot exact versions

Recent PyCharm versions also have Tools › Sync Python Requirements, which updates the file from the packages your code imports; review the result, since it cannot know about optional or runtime-only dependencies. For applications, pin exact versions (==) for reproducible installs; for libraries, specify compatible ranges in pyproject.toml instead.

Worked examples

Matplotlib

python -m pip install matplotlib installs prebuilt wheels on all mainstream platforms. In PyCharm, plt.show() renders into the IDE's Plots tool window when "Show plots in tool window" is enabled in the Python plotting settings; otherwise a separate window opens using an interactive backend. The common TkAgg backend requires tkinter; if you see errors about _tkinter, follow installing tkinter for PyCharm. In scripts that only save files, call matplotlib.use("Agg") before importing pyplot to avoid needing any display.

Pillow

The imaging library is installed as Pillow but imported as PIL. Installing by the import name fails, as this run with pip shows:

$ python -m pip install PIL
ERROR: Could not find a version that satisfies the requirement PIL (from versions: none)
ERROR: No matching distribution found for PIL

Install Pillow instead and keep from PIL import Image in your code. The same mismatch exists for opencv-python (import cv2), scikit-learn (import sklearn), beautifulsoup4 (import bs4) and PyYAML (import yaml). PyCharm's quick-fix on an unresolved import usually knows these mappings, but not always.

Kivy

Kivy's documented install command is python -m pip install "kivy[base]", which pulls prebuilt wheels for supported platforms and Python versions. Kivy typically adds wheels for a new Python release some time after it comes out; on a too-new interpreter pip falls back to building from source, which needs a compiler and SDL2 development libraries and usually fails. If that happens, create the project's virtualenv from a Python version listed on the Kivy installation page.

Quick verification script

After installing, a short script run from PyCharm confirms both the interpreter and the packages:

import sys
from importlib.metadata import version

print(sys.executable)
for dist in ("pillow", "matplotlib"):
    print(f"{dist:<11}", version(dist))

from PIL import Image
import matplotlib
matplotlib.use("Agg")            # no display needed
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [2, 4, 1])
fig.savefig("plot.png")
print(Image.open("plot.png").size)

With Pillow 13.0 and Matplotlib 3.11 installed in a fresh venv, it printed the interpreter path, both version numbers and (640, 480), the default size of a Matplotlib figure saved at 100 dpi.

Troubleshooting

"ModuleNotFoundError" although the package is installed

Print sys.executable in the failing script and compare it with where you installed the package (python -m pip show <name> prints the location).
Check the run configuration: Run › Edit Configurations can override the project interpreter for one script.
Make sure no file or folder in your project has the same name as the package (a local requests.py or numpy/ shadows the real one).
If the import works at runtime but the editor still underlines it, PyCharm's index is stale: File › Invalidate Caches and restart.

Proxy and SSL errors

PyCharm's own proxy setting (Settings › Appearance & Behavior › System Settings › HTTP Proxy) covers the IDE, but pip running in the terminal reads its own configuration. Set the proxy for pip with --proxy http://user:pass@host:port, the HTTPS_PROXY environment variable, or python -m pip config set global.proxy …. Behind a TLS-inspecting corporate proxy, CERTIFICATE_VERIFY_FAILED means pip does not trust the company's root certificate: point it at the correct CA bundle with --cert /path/to/ca.pem or pip config set global.cert. Avoid --trusted-host as a permanent fix, because it disables verification for that host. See the pip user guide for configuration file locations.

"Failed building wheel" or "Microsoft Visual C++ 14.0 or greater is required"

No prebuilt wheel exists for your Python version and platform, so pip tried to compile the package. Either use a Python version the package publishes wheels for, install it from conda-forge, or install a compiler toolchain. dlib is the classic example; the full procedure is in how to install dlib for PyCharm.

tkinter cannot be installed

Correct: tkinter is part of the standard library and comes with the interpreter, so it never appears in the package list. See installing tkinter for PyCharm.

"externally-managed-environment"

You are installing into a distribution-managed system Python (PEP 668). Create a virtual environment for the project instead of forcing it with --break-system-packages.

Summary

Packages belong to an interpreter, so confirm which one your project uses first. Then install through the Python Packages tool window, the interpreter settings list, or python -m pip in PyCharm's terminal. Use one virtualenv or conda environment per project, keep requirements.txt in sync, install packages by their distribution name (Pillow, not PIL), and treat "module not found" as an interpreter mismatch until proven otherwise.