【Python Development Primer】Setting Up and Running Python in VSCode

"I want to start programming, but I don't know where to begin..."
"The term 'environment setup' alone sounds difficult..."

Just a few months ago, I felt the exact same way. I started from zero knowledge, repeatedly hit the wall of errors, and spent my days searching for solutions. Now, with the help of AI, I've reached a point where I can launch websites on my own.

This article is a "Guide to Setting Up a Python Development Environment with VSCode," written as if I were writing it for my past self. I've tried to avoid jargon as much as possible and have packed it with my own experiences, including the points where I got stuck and the "aha!" moments that helped me understand.

The goal of this article isn't just to have you follow steps. It's for you to experience the small thrill of seeing the code you wrote with your own hands "run" on your PC, and to get the best possible start on your programming journey. I've included code that you can copy and paste to get it working, so please follow along with confidence!

STEP 1: Installing Python [The First and Most Crucial Hurdle!]

First, let's install the programming language Python on your PC. This is the first and most important step. In particular, forgetting one specific checkbox can lead you down a rabbit hole of "command not found!" errors later, so let's proceed carefully together.

Download the Installer from the Official Website

First things first, get the installer from the official Python website.

1. Go to the official Python download page.
2. Click the yellow button that says "Download Python x.x.x" to download the installer. (The latest stable version is fine.)

【Crucial】The Magic Checkbox During Installation

When you open the downloaded installer, the installation screen will appear. Here, the one thing you absolutely must not forget is to check the "Add python.exe to PATH" box at the bottom of the screen.

After checking the box, click "Install Now" to start the installation. Once it's complete, you can click "Close".

Let's Check if it Installed Correctly

Let's make sure your PC has properly met Python. Open "Command Prompt" or "PowerShell" on Windows, or "Terminal" on a Mac, and type the following command, then press Enter.

python --version

If you see something like Python 3.12.4, showing the version you installed, it's a great success! If you get an error, it's highly likely you forgot to check the "Add python.exe to PATH" box. In that case, try uninstalling Python and attempting this step again.

STEP 2: Installing VSCode (Visual Studio Code)

Next, let's install "VSCode," a high-performance editor for writing code. It's like a "Swiss Army knife" for programmers and can be used for development in any language, not just Python.

1. Go to the official VSCode download page.
2. Click the button for your OS (Windows, Mac) to download the installer.
3. Run the downloaded installer and follow the on-screen instructions. It's generally fine to leave all the settings as their defaults.

STEP 3: Customizing VSCode for Python! 【Extensions】

A fresh installation of VSCode is just a plain text editor. By installing "extensions," we can transform it into a super-powered Python development tool.

First, Let's Get VSCode in Your Language (Optional)

If you're not comfortable with English, you can change the language first. (This article assumes you're okay with English, but for other languages...)

1. Launch VSCode and click the icon on the left that looks like a stack of squares (the Extensions view).
2. In the search bar, type the name of your desired language pack, for example, "Japanese Language Pack".
3. Select the one with the globe icon that appears at the top and click the "Install" button.
4. After installation, click "Change Language and Restart" in the bottom right to restart, and the menus will be in your chosen language.

Essential Extensions for Python Development

Next, let's install the official Microsoft extension that makes Python development dramatically easier. In the same Extensions view, search for "Python".

Select the "Python" extension from Microsoft, which has a blue checkmark, and install it. This single extension provides you with the following key features:

• IntelliSense: A smart assistant that auto-completes your code. It reduces typos and speeds up development.
• Linting (Pylint): Points out grammatical errors in your code and non-recommended writing styles in real-time.
• Debugging: The ultimate tool for resolving errors, allowing you to execute code line by line while monitoring the state of variables.

STEP 4: Understanding "Virtual Environments" 【A Core Concept】

Alright, it's almost time to write some code! But before that, let me explain one more crucial concept that's standard practice in professional development: the "virtual environment." Understanding this will be a big step toward moving beyond the beginner stage.

Why Do We Need Virtual Environments?

When I first learned about this, I thought, "Why go through all this trouble?" In short, it's to "isolate the tools (libraries) used for each project."

Imagine you're building two different model kits.

• Model A's instructions say: "Use Glue X and Paint Y."
• Model B's instructions say: "Use the new Glue Z and the old version of Paint Y."

What if you only have one workbench? Glue X and Z would get mixed up, or using the new Paint Y might make the old Paint Y unusable... it would be chaos.

Programming is the same. It's common to need "version 1.0 of library X" for Project A, and "version 2.0 of library X" for Project B. If you install libraries globally on your PC (like throwing all your tools onto one desk), you can't handle these version conflicts, and your projects will break.

That's where "virtual environments" come in. It's like creating a dedicated "virtual workbench (toolbox)" for each project. By putting only the libraries needed for that specific project in this box, you prevent tools from getting mixed up with other projects.

Creating and Activating a Virtual Environment

Enough with the theory, let's actually create one.

1. Create a new folder somewhere you like, for instance, on your desktop. Let's name it "my-python-project".
2. Launch VSCode, go to the "File" menu, select "Open Folder...", and open the "my-python-project" folder you just created.
3. In VSCode, go to the "Terminal" menu and select "New Terminal" to open a terminal at the bottom of the screen.
4. In the terminal, type the following command and press Enter. This will create a virtual environment (a toolbox) named ".venv".

python -m venv .venv

Next, let's "activate" the toolbox we just made to start using it. Think of this as opening the lid of the toolbox. Note that the command differs depending on your OS.

【For Windows (PowerShell)】

.venv\Scripts\activate

【For Mac / Linux】

source .venv/bin/activate

If successful, you'll see a (.venv) prefix appear at the beginning of your terminal line. This is the sign that you are inside the virtual environment (the toolbox lid is open)!

STEP 5: Finally, Let's Run It! Displaying "Hello, World!"

Thanks for your patience! Everything is ready. It's time to run a program with your own hands.

1. In the VSCode Explorer view on the left, click the "New File" icon next to your "my-python-project" folder.
2. Name the file "main.py" and press Enter.
3. In the opened main.py file, try typing the following line yourself. (Copying and pasting is fine, but it's good practice to type it out at first!)

print("Hello, VSCode World!")

Once you've written the code, click the play-like button (▶) in the top-right corner of the VSCode window.

If you see the following output in your terminal, your first program ran successfully! Congratulations!

Hello, VSCode World!

This is that thrilling "it worked!" moment in learning to code. The accumulation of these small successes is the best motivation to keep learning.

STEP 6: Experience the Debugger [Making Friends with Errors]

It's normal for programs not to work as you expect. The most powerful weapon for finding the cause of errors in such times is the "debugger."

What is Debugging?

Debugging is the process of pausing a program mid-execution, carefully observing the contents of variables at that point, and removing bugs. Instead of randomly changing code, it allows you to scientifically identify the problem area.

Let's Set a Breakpoint

First, paste the following code into main.py.

name = "Copicode"
message = "Welcome to " + name
print(message)

num1 = 10
num2 = 20
total = num1 + num2
print(total)

Next, try clicking to the left of the line numbers in your code. A red dot (●) will appear. This is a "breakpoint," a marker that tells the debugger to pause here during a debug run. Let's set one on the line total = num1 + num2 (line 6).

Run the Debugger!

1. Press the F5 key, or open the "Run and Debug" view on the left (the icon with a bug and a play button) and press the "Run and Debug" button at the top.
2. If a dialog appears asking you to select a debug configuration, choose "Python File".

The program will start running but will pause just before the line with the breakpoint (after line 5 has executed). At this point, look at the "Variables" panel on the left side of the screen.

You can clearly see the values of variables like name, message, num1, and num2. The variable total from line 6, which has not yet been executed, is not there yet.

Press the "Step Over" (↓) button on the debug toolbar that appears at the top. The program will advance by one line, executing line 6. You should then see total: 30 added to the Variables panel.

By using the debugger like this, you can understand what's happening inside your program as if you were holding it in your hands. It allows you to find the cause of errors smartly without having to write lots of print statements.

【Advanced】Deepen the "It Worked!" Feeling with Libraries

"Hello, World!" is a fantastic first step, but the true power of programming is unleashed by using "libraries" (collections of useful tools) created by developers worldwide.

Here, let's use the ultra-popular library `requests` for communicating with external websites to run a simple program that fetches weather information.

1. Install the Library

Make sure your virtual environment is activated (you should see (.venv) at the start of your terminal line), then run the following command to add the `requests` library to your "toolbox."

pip install requests

pip is a handy command for managing Python libraries.

2. Code to Hit a Weather API

Erase all the content in main.py and paste the following code. This code fetches the weather forecast for Tokyo from a free API provided by the Japan Meteorological Agency.

# First, a declaration that we will use the requests library
import requests
import json

# API endpoint from the Japan Meteorological Agency (Tokyo's weather forecast)
url = "https://www.jma.go.jp/bosai/forecast/data/forecast/130000.json"

try:
    # Actually access the API and get the information
    response = requests.get(url)
    
    # Convert the retrieved information (JSON format) into a format Python can handle
    weather_data = response.json()
    
    # Format and display the information
    publishing_office = weather_data[0]["publishingOffice"]
    report_datetime = weather_data[0]["reportDatetime"]
    target_area = weather_data[0]["timeSeries"][0]["areas"][0]["area"]["name"]
    weather_info = weather_data[0]["timeSeries"][0]["areas"][0]["weathers"][0]

    print(f"Publishing Office: {publishing_office}")
    print(f"Report Datetime: {report_datetime}")
    print(f"Target Area: {target_area}")
    print(f"Today's Weather: {weather_info}")

except requests.exceptions.RequestException as e:
    print(f"A communication error occurred: {e}")
except json.JSONDecodeError:
    print("Failed to parse weather information.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

3. Let's Run It!

Run it as usual with the play button in the top right. If the current date and Tokyo's weather forecast are displayed in the terminal, it's a huge success!

With just a few lines of code, you've communicated with an external server and retrieved meaningful information. This is the fun and power of programming. Don't forget this feeling as you move on to your next learning adventure!

I am a programming beginner.
When I ran the following Python code, I got the error below.

# --- Paste your code here ---
(Paste the weather forecast code above)
# --- End of code ---

# --- Paste the error message here ---
(Paste the error from your terminal)
# --- End of error message ---

Please explain the cause of the error and what I should do to fix it, in a way that a beginner can understand.

Conclusion: To You, Who Has Made a Great Start

You've worked hard to get this far! You now have a perfect development environment for running Python programs with VSCode. But not only that, you've also gained:

• The thrill of seeing your code run
• A weapon for solving errors (the debugger)
• A reliable partner to turn to when you're stuck (AI)

This is an incredibly valuable asset on your programming learning journey.

Cherish the small success of "it worked!" that you experienced today, and continue to enjoy your learning. Your journey as a creator has only just begun!

Even if you didn't stumble during the environment setup, programming is full of various errors. As a next step, be sure to read the following article that summarizes common errors and their solutions.