A Rock-Solid Python and VSCode Setup That Just Works |

You know the feeling. VSCode is screaming at you about imports it can't find. You try to run a script, and it picks up the wrong Python version. Or PyTest swears there are no tests to run, even though they're staring you right in the face.

Ah! Enough.

Today, we're going to fix this. For good.

I'm going to walk you through a minimal, but complete, setup in VSCode that just... works. We'll get all the directories and paths set up in a way that actually makes sense. You'll be able to switch between Python environments, debug your code, and run your tests without pulling your hair out.

Plus, I'll share a few of my favorite settings and extensions, and we'll get auto-formatting set up so your code always looks clean. Let's do this.

The Tools of the Trade

First things first, you'll obviously need VSCode installed. But the next piece of the puzzle is managing your Python project and its dependencies.

You could go old-school and just install everything globally. Please don't. It's a recipe for disaster down the road.

For a long time, I used Poetry, and it's a fantastic, widely-used tool. It works great. But recently, I've switched to something new called UV, and I'm really liking it. It's fast and simple. I'm not going to do a deep dive here (that's for another video), but we'll use it for our setup.

UV handles a bunch of stuff for you, including virtual environments. If you're on a Mac like me, installing it with Homebrew is a breeze:

brew install uv

Next up, an auto-formatter. I'm using Ruff, which happens to be made by the same folks behind UV. It's incredibly fast. You can install it with Homebrew too:

brew install ruff

A quick note: if you're only using Ruff inside VSCode, the Ruff extension actually comes with it bundled, so you don't have to install it separately. But if you want to ensure your whole team uses the exact same version, you can add it as a project dependency.

My Go-To VSCode Extensions

I have a bunch of extensions, but for a solid Python setup, these are the essentials:

Ruff: The auto-formatter we just talked about.
Python (from Microsoft): This is the big one. It adds all the core Python language support.
Python Debugger (from Microsoft): Does what it says on the tin. Essential for debugging.

The main Python extension includes something called Pylance, which is the engine that provides all the smart stuff like autocompletion (IntelliSense) and error checking. You'll hear me mention Pylance a bit, because it's key to fixing one of our most annoying problems.

One more I'd recommend is EvenBetterTOML. Our project configuration lives in a pyproject.toml file, and this extension just makes it way easier to read with proper syntax highlighting and code folding. It's a small thing that makes a big difference.

Getting Your Project Structure Right

Okay, let's build our project.

Find a home for your code (like a ~/dev or ~/projects folder), create a new directory for your project, and cd into it.

If you're using Git (and you should be!), you can run git init or clone an empty repo from GitHub. Then, initialize the Python project with UV:

uv init --no-workspace

This gives you a super basic starting point: a hello.py, a README.md, and a pyproject.toml.

Now, let's organize it properly.

Create a src directory. This is where your actual application code will live.
Move hello.py into src and maybe rename it to main.py.
Create an empty file named __init__.py inside the src folder. This little file tells Python to treat the src directory as a package, which makes our imports much cleaner.
Create a tests directory for... well, your tests. We'll add a test_main.py file in there.

Your project should now look something like this:

my-project/
├── src/
│   ├── __init__.py
│   └── main.py
├── tests/
│   └── test_main.py
├── .gitignore
└── pyproject.toml

Now, let's add PyTest. Since it's only for development, we'll add it as a dev dependency:

uv add pytest --dev

UV will automatically add it to your pyproject.toml file, which is super convenient.

The Classic "Module Not Found" Problem

So you've written some code in src/main.py and a test for it in tests/test_main.py. You go to your terminal and run pytest.

And... ModuleNotFoundError.

It's a classic. PyTest has no idea that it's supposed to look for your code inside the src directory.

The fix is simple. Open your pyproject.toml and tell PyTest where to find your code. Add this little block:

[tool.pytest.ini_options]
pythonpath = "src"

Now, when you run pytest in the terminal, it works! The tests run, and all is right with the world.

...until you look back at VSCode.

The Final Boss: Fixing Imports in the Editor

Even though your tests are passing in the terminal, VSCode is probably still showing angry red squiggly lines under your imports in test_main.py. Pylance is confused. It still doesn't know about the src directory.

What's going on?

This is where understanding VSCode's settings scopes is crucial. There are three levels:

User Settings: Your personal preferences that apply everywhere (theme, font size, keybindings). These sync across your devices if you're logged in.
Workspace Settings: Settings for a specific VSCode window, which might contain multiple project folders. I usually just use this to set a custom color for the title bar so I can easily tell my projects apart.
Folder Settings: Settings specific to the project folder you have open. These live in a .vscode/settings.json file and are perfect for sharing project-specific configurations with your team.

The solution to our import problem lies in the Folder Settings. We need to tell Pylance where our code lives.

Create a .vscode folder in your project root, and inside it, create a settings.json file. Then, add this:

{
  "python.analysis.extraPaths": ["${workspaceFolder}/src"]
}

And just like that... the red squiggles vanish.

Pylance now knows to look in the src folder, so you get proper autocompletion, go-to-definition, and no more fake errors. Your terminal is happy, and your editor is happy.

This is the setup. This is the way.

All the code and configuration files I've shown you are in an example Git repository. You can find the link in the video description.

Now I'm curious, what are your must-have VSCode extensions or settings? Let me know in the comments.