Stop Failing at Environment Setup. A Complete Guide to GitHub Codespaces for Non-Engineers

"I wanted to start learning Python, but gave up because I got stuck on environment setup."

Have you ever had this experience? I work as BizDev and am certainly not an expert in Python. However, recently I've been able to develop data visualization dashboards and chatbots using Streamlit with the help of GitHub Codespaces and AI.

Why Does Programming Learning Fail at "Environment Setup"? - The 3 Walls That Programming Beginners Face

For people who are just starting to learn programming, environment setup is the most difficult step. It should be the first step, but you immediately hit a high wall. In this article, I'll introduce GitHub Codespaces to skip this step, but first, let me confirm what makes it so difficult.

1. Installing Languages and Runtime Environments (Terminal Operations)

To run the code you write, you need to install the runtime environment for that language on your machine. Programming languages and their runtime environments are not installed from app stores, but basically need to be installed from the terminal (the "black screen" that engineers use). Even when GUI-based installers are provided, you eventually need terminal operations when programming language version management becomes necessary.

At this point, the need to select procedures that match your OS and CPU architecture combination is also a difficult point. The procedures vary greatly depending on whether you have an Apple Silicon Mac, Intel (x86) Windows, or WSL.

2. Language Version Management and Virtual Environment Management

The next obstacle is situations where you need to specify runtime environment versions like "Python 3.11 or higher". For example, you want to use an open-source AI tool, but the Python installed locally is 3.9, and the documentation says Python 3.11 or higher is required... This tends to leave you wondering what to do. Also, in the case of Python, you might need virtual environment management.

3. It Doesn't Work Even Though I Followed the Instructions... (Troubleshooting)

The third wall is that "programs don't work for some reason" even when you follow the guide. Even though you should have done it according to the instructions, error messages appear.

Have you experienced spending enormous amounts of time just on environment setup and never quite getting to the actual programming learning? This is by no means uncommon.

Solution: What is GitHub Codespaces? - A Revolutionary Development Environment That Installs Nothing on Your PC

What solves this problem is GitHub Codespaces.

In one word: A cloud development environment where you can start programming immediately with just a browser. With just a few simple setup clicks, you get a development environment that's ready to use anytime.

Technical Mechanism (For Non-Engineers)

GitHub Codespaces is a system for borrowing computers in the cloud. You don't install anything on your PC - the programming environment runs on servers managed by GitHub.

Behind this is container technology (Docker is a representative example). Containers are technology that packages applications and their runtime environments, guaranteeing that they "work the same way on any computer". Since GitHub manages all the difficult settings, users can focus on development.

Peace of Mind: Codespaces Pricing Structure - Here's How Much You Can Use for Free

Codespaces has a free tier, so you can start without spending money first.

Free Tier Details

GitHub free accounts include 120 core hours of computing usage and 15GB/month of storage each month.

"Core hours" means "number of CPU cores × usage time". For example:

• Using a 2-core machine for 1 hour → consumes 2 core hours (can use up to 60 hours per month)
• Using a 4-core machine for 1 hour → consumes 4 core hours (can use up to 30 hours per month)

For beginner learning purposes, the default 2-core machine is sufficient. This means you can think of it as essentially 60 hours per month for free. With this much, you'll rarely use it up with just a few hours of learning per week.

Practice (Hands-On): Start in 5 Minutes! Let's Run Your First Python Environment

Let's actually experience GitHub Codespaces.

Step 1: Create GitHub Account

Skip this if you already have an account. Go to GitHub and create a free account.

Step 2: Launch Your First Codespace

1. Log in to GitHub
2. Select "New repository" from the "+" in the top right
3. Enter a repository name (e.g., my-first-codespace)
4. Check "Add a README file"
5. Click "Create repository"
6. On the created repository page, click the green "Code" button
7. Select the "Codespaces" tab
8. Click "Create codespace on main"

Success if the following screen opens! (Initial startup of Codespaces may take some time. Please wait until the screen switches.)

Step 3: Practical Mini-Project Experience

"Hello World" alone isn't interesting. Let's actually visualize some data.

First, let's create a data file.

Once Codespaces starts, create a new file data.csv and enter the following content:

Month,Sales
Jan,100
Feb,150
Mar,200
Apr,175
May,225

Next, let's create a Python script.

Create a new file main.py and enter the following code:

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv('data.csv')

plt.figure(figsize=(8, 6))
plt.plot(df['Month'], df['Sales'], marker='o')
plt.title('Monthly Sales Chart')
plt.xlabel('Month')
plt.ylabel('Sales (in 10k JPY)')
plt.grid(True)

plt.savefig('sales_chart.png')
print('Chart saved as sales_chart.png!')

Next, let's install libraries and run it.

The libraries needed for this project are pandas and matplotlib. Let's install them using uv, a fast package manager.

To use uv in Codespaces, you first need to install uv itself and create a Python virtual environment.

Run the following commands in the terminal (the black section at the bottom of the screen):

pip install uv
uv init
uv venv
uv add pandas matplotlib

A virtual environment is a mechanism for creating independent "workspaces" for each Python project. This prevents libraries used in Project A from conflicting with libraries used in Project B. The uv venv command easily creates this virtual environment.

If the above commands succeed, the necessary library installation is complete!

Execution screen in progress:

Execution completed screen:

Finally, let's execute the Python script:

python main.py

Execution completes in a few seconds, and a file called sales_chart.png is generated. Click this file to display the graph.

This gives you the real feeling that "development truly completes in the cloud without contaminating your own PC!"

Cost Management Best Practices

It's important to make stopping and deleting Codespaces a habit.

Always stop or delete Codespaces when you finish work. If left running, billing continues. Open Settings > Codespaces from the GitHub icon in the top right and set the Default idle timeout to 30 minutes (default).

Common pitfalls for beginners:

• Leaving multiple Codespaces running simultaneously
• Continuing to store large files in Codespaces
• Continuing to use without checking remaining free tier quota

Better Environment with .devcontainer Configuration

In the previous hands-on, we executed several commands in the terminal to set up the environment. While this allowed us to "get it working for now", Codespaces has a more convenient way to use it. That's using a special configuration file called .devcontainer.

By setting up this .devcontainer, every time you start a Codespace, the necessary tools and libraries are automatically installed, and the Python virtual environment is prepared. It's like having your own perfect development machine instantly launched in the cloud.

What is .devcontainer?

.devcontainer is a special folder placed in the project's root directory. Inside this, you create a configuration file named devcontainer.json.

The devcontainer.json file gives instructions to Codespaces like:

• Which OS image to use (e.g., Ubuntu-based image suitable for Python development)

• Which tools to install (e.g., uv command)

• What commands to execute when Codespaces starts (e.g., automatic installation of necessary libraries)

Having this file makes the development environment managed as "part of the code".

.devcontainer/devcontainer.json Configuration Example

Let's actually set it up so that pandas and matplotlib are automatically installed using uv.

1. Check the pyproject.toml and uv.lock files.

uv uses mainly the following two files to manage Python project dependencies:

• pyproject.toml: A file where the direct libraries needed for the project are described. This is used for human reading and writing, and is automatically updated with the uv add command.

• uv.lock: A file that records not only the libraries described in pyproject.toml but also all the sub-libraries they depend on, with exact versions and hash values of each library strictly recorded. This is a file that uv automatically generates and updates, and is essential for ensuring environment reproducibility.

By executing uv init and uv add pandas matplotlib earlier, these files have already been automatically created and updated. Please confirm that pyproject.toml and uv.lock exist in the project's root directory.

1. Create a .devcontainer folder in the project's root directory.

2. Inside that .devcontainer folder, create a file named devcontainer.json and copy and paste the following content:
   

{
  "name": "Python Development",
  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance"
      ],
      "settings": {
        "python.defaultInterpreterPath": "./.venv/bin/python",
        "python.terminal.activateEnvironment": true,
        "python.terminal.activateEnvInCurrentTerminal": true
      }
    }
  },
  "onCreateCommand": "pip install uv",
  "postCreateCommand": "uv sync && echo 'source .venv/bin/activate' >> ~/.bashrc",
  "remoteUser": "vscode"
}

1. Push (save) the changes to the GitHub repository.

Now the devcontainer.json configuration file is created. By saving these files to the GitHub repository, the next time you start a Codespace, the postCreateCommand in devcontainer.json will read these files and automatically build the exact same development environment.

Let's execute the following commands in order in the Codespaces terminal to push the changes to GitHub:

git add .
git commit -m "Add devcontainer setup"
git push

Now your Codespaces environment configuration is saved to GitHub, and you can reproduce the same environment from anywhere!

Key Points of This Configuration

• "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye": Specifies the base image for Codespaces. Here, we use Microsoft's official Dev Containers image (devcontainers/python) bullseye version with Python 3.11 pre-installed. This saves the trouble of Python environment setup.

• "customizations": This section mainly describes VS Code customization settings.

  • "vscode": VS Code specific settings.

    • "extensions": Specifies VS Code extensions that are automatically installed when Codespaces is created.

      • "ms-python.python": The official extension essential for Python development. Provides basic functions like code completion, debugging, and test execution.
      • "ms-python.vscode-pylance": Python's fast language server. Provides smarter code completion and type checking, improving development efficiency.

    • "settings": Overrides various VS Code settings.

      • "python.defaultInterpreterPath": "./.venv/bin/python": Specifies the path to the Python interpreter that VS Code uses by default. This usually points to the Python inside the virtual environment created by uv venv explained later.
      • "python.terminal.activateEnvironment": true and "python.terminal.activateEnvInCurrentTerminal": true: These settings are for automatically activating the Python virtual environment when VS Code's integrated terminal is opened. This saves the trouble of manually entering commands to enter the virtual environment every time you open the terminal.

• "onCreateCommand": "pip install uv": This command is executed when Codespaces is first created (or when the container is rebuilt). Here, we install the Python package management tool uv.

• "postCreateCommand": "uv sync && echo 'source .venv/bin/activate' >> ~/.bashrc": This command is automatically executed after onCreateCommand when Codespaces is first created (or when the container is rebuilt).

  • "uv sync": Based on the project's pyproject.toml and uv.lock files, installs all necessary libraries with exact versions and syncs the virtual environment. This saves environment setup trouble and automatically sets up a highly reproducible development environment.
  • "echo 'source .venv/bin/activate' >> ~/.bashrc": This part adds settings to the .bashrc file so that the Python virtual environment is automatically activated in all Bash terminals opened after Codespaces startup. This eliminates the need to manually execute source .venv/bin/activate every time you open a new terminal.

• "remoteUser": "vscode": Specifies the user to work with inside Codespaces. Here, we use the vscode user recommended by VS Code. This avoids file permission issues and allows smooth development.

Experience Environment Automation!

After committing the above changes to the GitHub repository, try "rebuilding" Codespaces once.

1. Open VS Code's command palette (Mac: Cmd + Shift + P / Windows/Linux: Ctrl + Shift + P).

2. Type "rebuild" and select and execute "Codespaces: Rebuild Container".

When the rebuild is complete, the moment you open the terminal, uv sync should be executed and the environment should be completely ready. Now you can start programming immediately without spending time on environment setup!

Try running main.py once:

python main.py

Now your GitHub repository with .devcontainer and uv.lock configured is no longer just a code storage ___location.

Using GitHub's fork feature (a feature that copies other people's repositories to your account), anyone can easily duplicate your repository and get the exact same development environment immediately just by starting a Codespace on top of it.

In other words, the environment you created functions as a "distributable development environment" where anyone can immediately start writing code just by publishing it on GitHub, without special setup guides! This makes project sharing and collaboration dramatically smoother.

Recommended Extension: Easy Code Generation with GitHub Copilot

What makes Codespaces even more convenient are VS Code extensions. I especially recommend GitHub Copilot for non-engineers.

GitHub Copilot is a tool where AI analyzes the code you're writing in real-time and automatically suggests the next code you should write. It also has a "chat feature" where you can ask questions about code or inquire about bug causes.

How to Use GitHub Copilot in Codespaces

Please modify your .devcontainer/devcontainer.json file as follows:

{
  "name": "Python Development",
  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "GitHub.copilot"
      ],
      "settings": {
        "python.defaultInterpreterPath": "./.venv/bin/python",
        "python.terminal.activateEnvironment": true,
        "python.terminal.activateEnvInCurrentTerminal": true
      }
    }
  },
  "onCreateCommand": "pip install uv",
  "postCreateCommand": "uv sync && echo 'source .venv/bin/activate' >> ~/.bashrc",
  "remoteUser": "vscode"
}

If you add this setting and rebuild Codespaces, the next time you start Codespaces, GitHub Copilot will be automatically enabled and code generation support will be displayed on screen.

For non-engineers, it's difficult to memorize all Python syntax and library usage. However, with GitHub Copilot, you can get appropriate code suggestions just by writing comments in Japanese. You can also ask questions in chat and resolve issues on the spot. This dramatically lowers the barrier to writing code from scratch and allows you to quickly turn ideas into reality.

By combining the comfortable development environment obtained with Codespaces with GitHub Copilot, the powerful AI support, non-engineers can fully enjoy the fun of programming and realize various ideas. Please start this new development experience!

Reference Links

• GitHub Codespaces Official Documentation
• Python Official Tutorial
• pandas Official Documentation
• matplotlib Official Documentation
• Streamlit Official Documentation