How to Run Pytest in PyCharm: A Complete Walkthrough

Running pytest in PyCharm takes about two minutes to set up correctly. Most developers spend two hours debugging why it isn’t working.

PyCharm’s test runner integration isn’t automatic. The right Python interpreter, the correct default runner, and a project structure pytest can actually discover all need to be in place before a single test runs.

This guide covers everything from configuring pytest as the default test runner to fixing the most common errors: import failures, “no tests were found,” and breakpoints that refuse to fire.

By the end, your test suite runs, your virtual environment is correctly linked, and debugging a failing test function takes one click instead of five terminal commands.

What Is Pytest in PyCharm

Pytest is a unit testing framework for Python. PyCharm is a dedicated Python IDE built by JetBrains. Together, they form one of the most practical test execution setups available for Python developers today.

The relationship between the two isn’t automatic. PyCharm doesn’t just “know” to use pytest. You configure it explicitly to treat pytest as the default test runner, and once that’s done, the IDE wraps pytest’s output inside a visual interface that makes reading test results, jumping to failures, and re-running specific tests much faster.

Why this matters: running pytest from the terminal is fine for quick checks, but PyCharm’s integration gives you clickable stack traces, a filterable results panel, and direct breakpoint debugging inside test functions. That combination saves real time on any project with a growing test suite.

According to the Python Developers Survey 2023 (JetBrains and PSF, 25,000+ respondents), pytest is used by 52% of Python developers for unit testing, compared to just 25% using the built-in unittest.

Pytest as a Framework vs. PyCharm as the Runner Layer

Pytest handles test discovery, test collection, fixture injection, and assertions. PyCharm adds a runner layer on top of that, calling pytest through its own internal runner script (jbpytestrunner.py) and capturing the output.

This separation matters when debugging configuration issues. If a test runs in the terminal but not through PyCharm’s green play button, the problem is almost always in the runner layer, not in pytest itself.

PyCharm Community vs. Professional for Testing

Both editions fully support pytest. The test runner, run configurations, debugging, and results panel all work in the free Community Edition.

Professional adds coverage reports via pytest-cov and deeper software testing lifecycle integrations like Django test support and database inspection. For running and debugging standard pytest test suites, Community is enough.

Among PyCharm users surveyed in 2023, 68% chose PyCharm Professional Edition as their primary IDE (JetBrains Python Developers Survey 2023).

Requirements Before Running Pytest in PyCharm

Three things must be in place before any test runs. Skip one and you’ll spend 20 minutes debugging a configuration error that has nothing to do with your actual tests.

• Python interpreter configured: PyCharm needs an active interpreter pointing to a local environment, virtualenv, or conda env.
• Pytest installed in that interpreter: Run pip install pytest inside the active environment, not just globally.
• Project structure PyCharm recognizes: Test files named test.py or test.py, placed in directories marked as Test Sources in PyCharm’s Project Structure settings.

The third point catches a lot of people. PyCharm’s test discovery depends on both naming conventions and directory configuration. A file called mytests.py in a folder not marked as a test root won’t show up, regardless of what’s inside it.

Python Interpreter Setup Check

Look at the bottom-right corner of the PyCharm window. The active interpreter name is always visible there.

If it shows “No interpreter” or points to a system Python where pytest isn’t installed, that’s your problem before anything else. Click it to open interpreter settings and either add the correct environment or create a new virtualenv directly from that menu.

The JetBrains Python Developers Survey 2024 (30,000+ respondents) found that 40% of Python developers use three or more IDEs or editors simultaneously, which means interpreter mismatches across environments are genuinely common, not edge cases.

Project Structure That Pytest Can Discover

Pytest expects one of two standard layouts:

In PyCharm, right-click the tests/ folder and choose Mark Directory As > Test Sources Root. This tells both PyCharm’s test discovery engine and pytest where to look. Missing this step is the most common cause of “no tests were found” errors.

How to Set Pytest as the Default Test Runner in PyCharm

PyCharm defaults to autodetect for the test runner. That sounds convenient, but it creates problems when a project has both pytest and unittest present, or when pytest wasn’t installed at project creation time. Setting it explicitly takes 30 seconds and prevents a lot of confusion.

Navigating to Python Integrated Tools

Open Settings (Windows/Linux: Ctrl+Alt+S) or Preferences (Mac: Cmd+,). Go to Tools > Python Integrated Tools.

The “Default test runner” dropdown is in the Testing section. Change it from “Autodetect” to “pytest” and click Apply.

If pytest isn’t installed in the current interpreter, PyCharm shows a “pytest not found” notice with a Fix button directly on that settings page. Clicking Fix installs pytest into the active environment automatically.

Project-Level vs. Global Settings

Project-level setting: applies only to the current project. PyCharm saves it in .idea/. Best for team repos where test runner choice should be version-controlled.

Global default: applies to all new projects. Set this if you always use pytest and don’t want to configure it per project. Existing projects aren’t affected by changing the global default.

Teams working on mixed codebases (some projects using unittest, others pytest) should always configure at the project level to avoid conflicts.

What Happens to Existing Cached Configurations

If you change the test runner after PyCharm has already created run configurations using unittest, those existing configurations won’t update automatically. You’ll need to go to Run > Edit Configurations and delete the old unittest configurations. New ones using pytest get created the next time you click the play button next to a test function.

This catches a lot of people who change the setting and then wonder why the behavior hasn’t changed. The old configuration takes priority over the new default until you remove it.

How to Run Pytest Tests Directly from PyCharm

Once pytest is set as the default runner, there are four ways to trigger a test run. Each suits a slightly different scenario.

Using the Gutter Play Button

The green arrow appears in the left gutter next to any function starting with test or any class starting with Test. Click it to run that specific test or test class in isolation.

This is the fastest path for running a single failing test during debugging. No configuration needed. PyCharm creates a temporary run configuration on the fly.

Keyboard shortcut: place the cursor inside a test function and press Ctrl+Shift+F10 (Windows/Linux) or Ctrl+Shift+R (Mac) to run it without touching the mouse.

Right-Click and Run Menu

Right-clicking a test file in the Project panel gives you Run ‘pytest in [filename]’. This runs all tests in that file.

Right-clicking a folder runs all tests in that directory recursively. Useful when you want to run tests for one module without triggering the full test suite.

Run Menu and Toolbar

The top-right toolbar shows the currently selected run configuration. If a pytest configuration is already saved, selecting it from the dropdown and clicking Run (or pressing Shift+F10) runs the entire configuration.

This is how most developers run the full test suite before committing. One keyboard shortcut, full results in the Run panel.

Re-Running Failed Tests Only

After a test run, the results panel shows a rerun icon (two circular arrows) next to failed tests. Clicking Rerun Failed Tests runs only the tests that didn’t pass in the previous run.

This is genuinely useful on large test suites. No need to pass --last-failed manually via the terminal. PyCharm surfaces it as a single click.

How to Create and Configure a Pytest Run Configuration

Temporary run configurations disappear between sessions. A saved run configuration persists, carries specific arguments, and can be shared with a team. This is the setup worth spending a few minutes on.

Creating a New Pytest Configuration

Go to Run > Edit Configurations. Click the + button and choose Python tests > pytest.

Fill in:

• Name: something descriptive like “Run all tests” or “Unit tests only”
• Script path or Module: point to the test file, directory, or leave blank to run from the project root
• Working directory: usually the project root
• Python interpreter: confirm it matches your active environment

Passing Arguments to Pytest

The “Additional Arguments” field in the run configuration accepts any pytest CLI flag.

I use -v --tb=short as a baseline for most configurations. Verbose enough to see what’s running, short enough that failure output doesn’t scroll off screen.

Specifying a Custom Config File

If the project uses pytest.ini, pyproject.toml, or setup.cfg for pytest configuration, PyCharm picks them up automatically when the working directory is set correctly.

For non-standard locations, add -c path/to/pytest.ini to the Additional Arguments field. This tells pytest explicitly which config file to load, overriding any default discovery.

How to Run Pytest with a Virtual Environment in PyCharm

This is where most “pytest not found” problems actually originate. The issue isn’t pytest. It’s that PyCharm is pointing at an interpreter where pytest isn’t installed.

Confirming the Active Interpreter

The active interpreter always shows in the bottom-right status bar. For a virtualenv project, it should say something like Python 3.11 (venv), not the system Python path.

If it shows a system Python and your pytest is installed in a venv, every test run will fail with ModuleNotFoundError: No module named 'pytest'. The fix isn’t reinstalling pytest. It’s switching to the correct interpreter.

Adding a Virtualenv or Conda Environment

Go to Settings > Project > Python Interpreter. Click the interpreter dropdown and choose Add Interpreter > Add Local Interpreter.

For virtualenv: choose “Existing environment” and point to the python executable inside the venv folder (e.g., venv/bin/python on Mac/Linux or venvScriptspython.exe on Windows).

For conda: choose “Conda Environment” and either create a new one or select an existing conda environment from the list.

Verifying Pytest Is Installed in That Environment

After switching interpreters, open the PyCharm terminal (which automatically activates the project’s interpreter) and run:

 pip show pytest 

If that returns nothing, pytest isn’t in that environment. Install it with pip install pytest directly in that terminal window. Then re-check Settings > Tools > Python Integrated Tools to confirm PyCharm has detected it.

According to JetBrains support forums, the combination of “wrong interpreter + pytest not installed there” accounts for the overwhelming majority of reported pytest not found in PyCharm issues. The solution is always the same: match the interpreter to the environment where pytest lives.

How to Debug Pytest Tests in PyCharm

Debugging test failures via print() statements is a habit that gets tricky fast. Pytest captures stdout by default, so print output doesn’t show unless you pass -s. And you’re now modifying test code just to investigate a problem.

PyCharm’s debugger is built specifically for this. Set a breakpoint, click Debug instead of Run, and execution pauses exactly where you need it. No terminal flags, no extra code, no cleanup after.

Developers and QA teams spend significant time debugging. A LinkedIn analysis from 2024 cited estimates that 20-40% of developer time goes to debugging, making fast, visual debugging tools directly relevant to daily productivity.

Setting Breakpoints Inside Test Functions

Click in the left gutter of any line inside a test function. A red circle appears confirming the breakpoint is set.

Then right-click the green gutter icon next to the test function and choose Debug ‘pytest for [test name]’, not Run. PyCharm launches the test under its visual debugger and pauses at the breakpoint.

From there: inspect variables in the Debug panel, step through lines with F8, step into function calls with F7, or press F9 to continue to the next breakpoint.

When Breakpoints Don’t Fire

This trips up a lot of people. The test runs but execution never pauses. Usually one cause: pytest-cov is active.

Coverage analysis uses Python’s sys.settrace API. PyCharm’s debugger uses the same API. They conflict, and coverage wins. The fix: add –no-cov to the Additional Arguments field in your run configuration. That disables coverage for that specific debug session without removing it from your normal test runs.

PyCharm Debugger vs. pytest.settrace()

For day-to-day work inside PyCharm, the gutter breakpoint wins. Took me longer than I’d like to admit to stop reaching for print() and just use it.

How to View and Interpret Pytest Output in PyCharm

After a test run, the Run tool window opens at the bottom. This is where most developers spend time after a failure, and knowing exactly what each part shows saves a lot of clicking around.

The Run Tool Window vs. the Terminal

Run tool window: PyCharm’s visual layer over pytest output. Shows a tree of test files, classes, and individual test functions with color-coded pass/fail/skip icons. Click any failed test to jump straight to the failure line in the editor.

Terminal output: the raw pytest output, visible in the console tab of the same window. Useful when you need to see the exact error message text, copy a traceback, or check what arguments pytest received.

Both views are available simultaneously. Switch between them with the tabs at the top of the Run window.

Reading Passed, Failed, Skipped, and Error States

PyCharm maps pytest’s exit states to visual indicators:

• Green checkmark: test passed
• Red X: test failed (assertion error or exception)
• Yellow circle: test skipped (@pytest.mark.skip or skipif)

• Orange warning: test collection error, not a test failure

Collection errors (orange) mean pytest couldn’t even import or discover the test. These are almost always import errors or PYTHONPATH problems, not issues with the test logic itself.

Filtering and Re-Running from the Results Panel

The toolbar inside the Run window has filter buttons that narrow results to just passed, failed, or skipped tests. After a long test suite run, clicking “Show failed tests only” cuts through the noise immediately.

The Rerun Failed Tests button (two circular arrows) re-runs only the tests that failed in the last run. No configuration changes needed. This is equivalent to running pytest –last-failed from the terminal, but without leaving the IDE.

Stack Overflow’s 2024 Developer Survey found that respondents spent more than 30 minutes per day searching for solutions to technical problems. Faster test result navigation directly cuts into that number during active debugging sessions.

Common Pytest Errors in PyCharm and How to Fix Them

Most errors fall into a short list. Recognizing the pattern quickly gets you back to writing code instead of debugging configuration.

“No Tests Were Found”

Three causes, in order of likelihood:

• Wrong test runner: PyCharm is still using unittest. Check Settings > Tools > Python Integrated Tools and confirm pytest is selected.
• Naming convention violated: test files must start with test or end with test.py. Test functions must start with test.

• Directory not marked as Test Sources Root: right-click the tests folder and choose Mark Directory As > Test Sources Root.

The JetBrains community forum shows this as one of the most frequently reported pytest issues in PyCharm. Nearly every thread resolves with one of the three fixes above.

Import Errors During Test Collection

You see something like: ModuleNotFoundError: No module named ‘myapp’ during collection, even though the module exists in the project.

The project root isn’t in sys.path for that run configuration. Fix it by setting PYTHONPATH explicitly in the run configuration’s environment variables field: add PYTHONPATH=$PYTHONPATH:$PROJECTROOT.

For src-layout projects, add the src/ directory to PYTHONPATH. Alternatively, add a conftest.py file at the project root. Pytest automatically adds the conftest.py directory to sys.path on startup, which resolves most import issues without manual path configuration.

Pytest Plugin Conflicts

Plugins like pytest-django, pytest-asyncio, and pytest-cov occasionally break when their versions don’t align with the installed pytest version.

Symptom: tests that run fine in the terminal fail immediately in PyCharm with a plugin-related traceback.

Fix: check plugin compatibility. Run pip show pytest pytest-django (or whichever plugin) and compare versions against the plugin’s changelog. Most plugin authors document which pytest versions are supported. Pinning compatible versions in requirements.txt prevents this from reappearing after updates.

PyCharm Running Unittest Instead of Pytest

This happens when an existing unittest run configuration takes priority over the pytest default. The gutter icon triggers the cached configuration, not the newly set default.

Go to Run > Edit Configurations. Delete any configuration with type “Python tests/Unittests.” Then click the gutter play button again. PyCharm creates a fresh pytest configuration using the default runner.

This also happens after upgrading PyCharm versions. The IDE occasionally resets the default test runner during major version updates. Worth checking Settings > Tools > Python Integrated Tools after any upgrade to confirm pytest is still selected.

For a broader view of how pytest fits into the larger picture of types of software testing, including where unit tests sit relative to integration and end-to-end tests, the distinction matters when deciding how to structure your test suite and what to run locally vs. in CI.

Teams practicing test-driven development will run pytest in PyCharm constantly during the red-green-refactor cycle. PractiTest’s State of Testing 2024 report found that TDD adoption grew from 18% to 23% between 2023 and 2024, meaning more teams are running tests as part of writing code, not after. Having a fast, frictionless pytest setup in PyCharm directly supports that workflow.

Teams using regression testing alongside pytest can also automate reruns of previously passing tests on every commit, catching breakage early without manual effort. The PyCharm vs. IntelliJ IDEA comparison is worth reading if your team works across multiple languages, since IntelliJ supports pytest via the Python plugin but with fewer Python-specific testing conveniences than a dedicated PyCharm setup.

And if you’re curious how the same pytest workflow translates to a different editor, the VSCode vs PyCharm breakdown covers the key differences in how each IDE handles test discovery, runner configuration, and debugging.

FAQ on How To Run Pytest In PyCharm

How do I set pytest as the default test runner in PyCharm?

Go to Settings > Tools > Python Integrated Tools and change the Default test runner dropdown to pytest. Click Apply. PyCharm will use pytest for all new run configurations in that project going forward.

Why does PyCharm say “No tests were found”?

Usually a naming issue or wrong runner. Test files must start with test or end with test.py. Also confirm pytest is set as the default runner and the tests folder is marked as a Test Sources Root.

How do I install pytest in PyCharm?

Open the PyCharm terminal and run pip install pytest. This installs pytest into the currently active interpreter. Confirm the correct virtual environment is active first by checking the interpreter name in the bottom-right status bar.

Can I run a single test function in PyCharm?

Yes. Click the green gutter arrow next to the test function and select Run. Alternatively, place your cursor inside the function and press Ctrl+Shift+F10 on Windows/Linux or Ctrl+Shift+R on Mac.

Why is PyCharm running unittest instead of pytest?

An old unittest run configuration is taking priority. Go to Run > Edit Configurations, delete any unittest configuration, then re-trigger the test. PyCharm will create a fresh pytest configuration using the current default runner.

How do I debug a pytest test in PyCharm?

Set a breakpoint by clicking in the left gutter next to any line inside the test. Right-click the gutter play icon and choose Debug. PyCharm pauses execution at the breakpoint, letting you inspect variables directly in the Debug panel.

Why aren’t my breakpoints firing during pytest debugging?

Most likely pytest-cov is active. Coverage analysis uses the same Python tracing API as the debugger, causing a conflict. Add –no-cov to the Additional Arguments field in your run configuration to fix it.

How do I run pytest with a virtual environment in PyCharm?

Confirm the correct interpreter is active in the bottom-right status bar. If it shows a system Python, go to Settings > Project > Python Interpreter and switch to your virtualenv or conda environment where pytest is installed.

How do I pass arguments to pytest in PyCharm?

Open Run > Edit Configurations, select your pytest configuration, and add flags to the Additional Arguments field. Common options include -v for verbose output, -s to show print statements, and -k “testname” to filter by test name.

Does PyCharm Community Edition support pytest?

Yes, fully. Test discovery, run configurations, the results panel, and breakpoint debugging all work in the free Community Edition. PyCharm Professional adds extras like code coverage reports via pytest-cov and Django test integration.

Conclusion

This conclusion is for an article presenting how to run pytest in PyCharm, a setup that removes friction from the entire test execution workflow.

Once the run configuration is saved, the correct interpreter is active, and your test suite is properly discovered, the whole process becomes fast and repeatable.

Debugging failing tests with PyCharm’s visual debugger beats digging through terminal output every time. Breakpoints, variable inspection, and one-click reruns of failed tests are genuinely useful on any project with real test coverage.

The common errors covered here, from PYTHONPATH conflicts to plugin interference, all follow the same diagnostic logic: check the interpreter, check the runner, check the directory structure.

Fix those three things and pytest runs exactly the way it should.

• Author
• Recent Posts

Bogdan Sandu

Bogdan Sandu is a front-end developer at TMS Outsource with 8+ years of experience in web technologies. He writes about developer tools, software platforms, and web workflows based on daily hands-on use.

Latest posts by Bogdan Sandu (see all)

• How to Install Plugins in Notepad++ - August 3, 2026
• Best 5 AI Penetration Testing Tools for Web and Mobile Applications - August 2, 2026
• Android App Bundle vs APK - August 1, 2026