PyCharm and uv: a calm first workflow for scientific Python projects

For a small research project, a good Python environment matters more than it first appears. PyCharm helps you inspect code, notebooks, tests, and project files in one place, while uv gives you a fast and repeatable way to create environments and install dependencies.

1. Start with the project folder

Open the repository folder directly in PyCharm. A project should have one clear root that contains files such as pyproject.toml, source code, tests, and documentation. Avoid opening a nested folder unless the repository is intentionally split into subprojects.

2. Use uv for the environment

uv can create and manage the virtual environment from the project metadata. In a terminal, run uv sync to install dependencies. Then run commands through the environment with uv run, for example uv run pytest or uv run python script.py.

3. Point PyCharm at the same interpreter

After uv creates .venv, configure PyCharm to use that interpreter. This keeps editor inspections, test runs, and terminal commands aligned. If imports work in the terminal but not in the editor, the interpreter setting is the first place to check.

4. Keep tests close to the workflow

For scientific code, tests do not need to be elaborate at first. A useful starting point is a few small tests that check known values, parse one real output file, or confirm that a plotting/data pipeline can run without crashing.

5. A practical command list

• uv sync: install the project dependencies.
• uv run pytest: run tests in the managed environment.
• uv add package-name: add a dependency to the project.
• uv run python -m module: run a module through the environment.

The key habit is consistency: use the same project root, the same interpreter, and the same command runner. That alone removes many confusing setup problems before they become research delays.