Setting Up a Beginner-Friendly Python Workspace

What “Python Workspace” Means (and Why It Matters)

A beginner-friendly Python workspace is the set of tools and habits you use to write, run, and organize Python code without friction. It usually includes: a Python installation (the interpreter), a place to write code (an editor or IDE), a way to run code (terminal, run button, or notebook), and a way to keep each project’s dependencies separate (virtual environments). When these pieces are set up well, you spend your time learning Python instead of fighting confusing errors like “python not found,” mismatched versions, or packages installed in the wrong place.

In this chapter, you will set up a workspace that is simple, reliable, and easy to troubleshoot. The goal is not to install every tool available, but to choose a small set of tools that work together predictably.

Choose Your Setup Style: Simple First, Powerful Later

There are two common beginner-friendly ways to work with Python:

• Editor + Terminal workflow: You write code in a code editor (for example, Visual Studio Code) and run it in a terminal. This is a great default because it matches how many real projects are built and makes it easier to understand what is happening.

• Notebook workflow: You write code in cells (for example, Jupyter Notebook). This is excellent for experimenting and learning, but it can hide some details about files and project structure.

  Continue in our app.

  You can listen to the audiobook with the screen off, receive a free certificate for this course, and also have access to 5,000 other free online courses.

  Or continue reading below...

  

  Download the app

You can use both. A practical approach is: use an editor for scripts and small projects, and use notebooks for exploration.

Step 1: Install Python the Beginner-Safe Way

Python is the program that runs your code. Your editor is not enough by itself; it needs a Python interpreter installed on your computer.

Windows: Install from python.org (Recommended)

• Download the latest stable Python 3 release from the official Python website.

• During installation, make sure to check the option “Add Python to PATH”. This makes it possible to run python from the terminal.

• Choose the default installation options unless you have a specific reason to change them.

After installing, open PowerShell or Command Prompt and run:

python --version

If that does not work, try:

py --version

On Windows, the py launcher is common and often more reliable than python.

macOS: Use the Official Installer (Beginner-Friendly)

macOS includes a system Python in some versions, but it may be outdated or reserved for system tools. A beginner-friendly approach is to install a separate Python from the official Python website.

• Download the macOS installer package from the official Python website.

• Install it using the default options.

Then open Terminal and run:

python3 --version

On macOS, you often use python3 instead of python.

Linux: Use Your Package Manager (Usually)

Many Linux distributions already include Python 3. You can check:

python3 --version

If you need to install it, use your distribution’s package manager. The exact command depends on your distribution.

Step 2: Verify Python and pip Are Working

pip is Python’s package installer. You will use it to install extra tools and libraries. Verify it works:

python -m pip --version

On macOS/Linux you may need:

python3 -m pip --version

Using python -m pip is a good habit because it guarantees you are using the pip that belongs to that specific Python interpreter.

Quick Troubleshooting: “pip not found”

• Try python -m pip instead of pip.

• If Python is installed but pip is missing, you may need to reinstall Python using the official installer and ensure pip is included.

Step 3: Install a Code Editor (VS Code Recommended)

A code editor is where you write and manage your files. Visual Studio Code (VS Code) is a popular choice for beginners because it is free, works on all major operating systems, and has strong Python support.

Install VS Code and the Python Extension

• Install VS Code from the official website.

• Open VS Code and install the Python extension (published by Microsoft).

This extension helps with syntax highlighting, running scripts, selecting interpreters, and formatting.

Set VS Code to Use the Right Python

VS Code can detect multiple Python installations. You want it to use the one you installed (and later, the one inside your virtual environment).

• Open the Command Palette (usually Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS).

• Search for Python: Select Interpreter.

• Choose the interpreter that matches your installed Python version.

If you are not sure which one is correct, you can open a terminal in VS Code and run:

python --version

or on macOS/Linux:

python3 --version

Step 4: Create a Simple Project Folder Structure

Beginners often save files on the desktop with names like test.py. That works for a day, but it becomes confusing quickly. A simple structure makes it easier to find your work and avoid mixing unrelated files.

Create a main folder for your Python projects, for example:

Projects/

Inside it, create one folder per project:

Projects/hello-python/

Inside a project folder, a beginner-friendly structure might look like:

hello-python/  main.py  README.md  .venv/

Notes:

• main.py is your script file.

• README.md is optional but useful for notes about what the project does and how to run it.

• .venv/ will be your virtual environment (explained next).

Step 5: Use Virtual Environments (So Projects Don’t Break Each Other)

A virtual environment is an isolated Python setup for a specific project. It keeps installed packages separate per project. This prevents problems like: you install a package for one project, and it accidentally changes or breaks another project.

Even if you are a beginner, using a virtual environment from the start is a strong habit and saves time later.

Create a Virtual Environment

Open a terminal inside your project folder (for example, hello-python), then run:

python -m venv .venv

On macOS/Linux, if your command is python3:

python3 -m venv .venv

This creates a folder named .venv containing a local Python interpreter and local site-packages.

Activate the Virtual Environment

Activation changes your terminal session so that python and pip point to the environment inside .venv.

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Windows (Command Prompt):

.venv\Scripts\activate.bat

macOS/Linux (bash/zsh):

source .venv/bin/activate

After activation, you often see (.venv) at the start of your terminal prompt.

Confirm You Are Using the Environment’s Python

Run:

python --version

Then check where Python is coming from:

python -c "import sys; print(sys.executable)"

The printed path should point into your project’s .venv folder.

Install Packages Inside the Virtual Environment

With the environment activated, install packages like this:

python -m pip install requests

This installs requests only for this project, not globally.

Keep Track of Dependencies with requirements.txt

When you install packages, it is helpful to record them so you (or someone else) can recreate the environment later.

To create a dependency list:

python -m pip freeze > requirements.txt

To install dependencies from that file in a fresh environment:

python -m pip install -r requirements.txt

Step 6: Configure VS Code to Use Your Virtual Environment

VS Code can automatically detect virtual environments, but it helps to know how to select the correct one.

• Open your project folder in VS Code (File → Open Folder).

• Open the Command Palette and choose Python: Select Interpreter.

• Select the interpreter that points to .venv.

Once selected, VS Code will use that environment when you run scripts and when it provides code suggestions.

Step 7: Run Python Code Reliably (Terminal and Run Button)

There are two common ways to run a Python script in VS Code.

Option A: Run from the Terminal (Most Transparent)

Create a file named main.py in your project folder with a simple test:

print("Workspace is ready!")

Then run it in the terminal (with your virtual environment activated):

python main.py

If you see the message printed, your workspace is working.

Option B: Use VS Code’s Run Feature

VS Code can run the current file using a play button or context menu. This is convenient, but if something goes wrong, the terminal method is easier to debug because you can see exactly which command is being executed.

If the Run feature uses the wrong interpreter, re-check your selected interpreter and confirm that .venv is active or selected.

Step 8: Add Basic Quality-of-Life Tools (Formatting and Linting)

Formatting and linting help you write readable code and catch mistakes early. Beginners benefit because it reduces “mystery errors” caused by inconsistent formatting or typos.

Install a Formatter (Black) in Your Virtual Environment

With the environment activated:

python -m pip install black

Then in VS Code settings, choose Black as the formatter (VS Code can guide you through this when you format a file). A common setup is “format on save,” so your code is automatically formatted whenever you save.

Install a Linter (Ruff) in Your Virtual Environment

Ruff is fast and beginner-friendly because it provides clear warnings and suggestions.

python -m pip install ruff

In VS Code, enable Ruff through the appropriate extension or settings so warnings appear as you type.

If you prefer fewer tools at first, you can skip linting and add it later. Formatting alone already helps a lot.

Step 9: Understand the Terminal You Are Using

Many beginner issues come from running commands in the wrong place. A few habits make the terminal much easier:

• Know your current folder: Use pwd (macOS/Linux) or cd (Windows) to see where you are.

• List files: Use ls (macOS/Linux) or dir (Windows) to confirm your script is there.

• Run commands from the project folder: This ensures relative paths and imports behave as expected.

In VS Code, using “Terminal → New Terminal” usually opens a terminal already pointed at your project folder, which reduces mistakes.

Step 10: Common Setup Problems and How to Fix Them

Problem: “python is not recognized” (Windows)

• Try py instead of python.

• Re-run the Python installer and ensure “Add Python to PATH” is checked.

• Close and reopen your terminal after installation changes.

Problem: VS Code Runs the Wrong Python

• Use Python: Select Interpreter and choose the one inside .venv.

• Open the integrated terminal and run python -c "import sys; print(sys.executable)" to confirm.

• If you opened a single file instead of the whole folder, open the project folder so VS Code can detect .venv properly.

Problem: Packages Install but Import Fails

This usually means you installed a package into one Python environment but are running code with another.

• Activate your virtual environment and reinstall the package using python -m pip install ....

• Confirm the interpreter path with sys.executable.

Problem: PowerShell Blocks Activation Script (Windows)

PowerShell may prevent running the activation script due to execution policy settings. A common fix is to run PowerShell as your normal user and allow scripts for the current session or user. If you prefer to avoid this, you can use Command Prompt activation instead, or use VS Code’s interpreter selection without manual activation.

Optional: Add Jupyter Notebooks for Practice

If you want an interactive environment for experimenting, you can add Jupyter to your virtual environment. This keeps notebooks tied to the same dependencies as your project.

Install Jupyter in the Virtual Environment

python -m pip install jupyter

Start it:

python -m jupyter notebook

Or, if you use VS Code, install the Jupyter extension and create a new notebook file. Make sure the notebook kernel is set to your .venv interpreter so imports work consistently.

Optional: A Minimal “Workspace Checklist” You Can Reuse

When starting a new project, you can follow this repeatable checklist:

• Create a new project folder.

• Open the folder in VS Code.

• Create a virtual environment: python -m venv .venv.

• Activate it (or select it in VS Code).

• Upgrade pip (optional but helpful): python -m pip install --upgrade pip.

• Install what you need: python -m pip install ....

• Save dependencies: python -m pip freeze > requirements.txt.

• Create main.py and run: python main.py.

Safety and Organization Tips for Beginners

• Avoid naming your file the same as a library: For example, do not name your script random.py or requests.py, because it can confuse Python’s import system.

• Keep one project per folder: Mixing unrelated scripts in one folder makes it harder to manage dependencies and files.

• Use consistent naming: Choose simple, lowercase names with hyphens or underscores for folders and files.

• Don’t install everything globally: Prefer virtual environments so you can reset or delete a project without affecting others.