Complete Python Project Setup: A Step-by-Step Guide

Every new Python project deserves the same solid foundation: a proper virtual environment, dependencies locked in pyproject.toml, secrets safely stored in a .env file, and the whole thing backed up on GitHub. Doing this consistently from the start takes less than ten minutes and saves hours of debugging and recovery work later. Run through these steps for every project — including the small ones — until it becomes second nature.

Step 1: Open your terminal

# Terminal app or iTerm

# Terminal, Command Prompt, or PowerShell

Step 2: Navigate to your projects folder

cd ~/Documents/Projects       # macOS
cd C:\Users\YourName\Documents\Projects  # Windows

Create a single dedicated folder (like Projects/ or repos/) for all your Python work. It keeps things organized and makes it easy to find any project later.

Step 3: Create the project with uv

uv init my-awesome-project

uv init generates a complete starting structure:

my-awesome-project/
├── .gitignore       # Already ignores .venv, .env, __pycache__
├── .python-version  # Pins the Python version
├── pyproject.toml   # Project config and dependency declarations
├── README.md        # Project description
└── main.py          # Example entry-point

The .venv folder and uv.lock are created automatically when you first run uv add. You don’t need to do anything extra.

Step 4: Open in VS Code

cd my-awesome-project
code .

VS Code opens with your project, the Python extension activates, and the virtual environment is detected automatically.

If code . doesn’t work, see the Git section for instructions on enabling the code shell command.

Step 5: Add your dependencies

Open the integrated terminal in VS Code (Ctrl + `):

uv add requests
uv add pandas numpy
uv add python-dotenv

# Optional — adds interactive Python support
uv add ipykernel

Each uv add call updates pyproject.toml and uv.lock automatically.

Step 6: Test that everything works

Edit main.py to verify your setup:

import requests
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

print("✅ Packages imported successfully!")

# Verify environment variable loading
api_key = os.environ.get("API_KEY", "not-set")
print(f"✅ API_KEY: {api_key}")

# Verify network access
response = requests.get("https://api.github.com")
print(f"✅ GitHub API status: {response.status_code}")

uv run python main.py

All three lines should print without errors.

Step 7: Set up environment variables

Create .env for your actual secrets (this file stays on your machine only):

# .env
API_KEY=your-secret-key-here
DATABASE_URL=postgresql://localhost/mydb
DEBUG=True

Create .env.example to document what variables are needed (this file is safe to commit):

# .env.example
API_KEY=your-api-key-here
DATABASE_URL=your-database-url
DEBUG=True

.env is already listed in the .gitignore that uv init created. Confirm it’s there before your first commit.

Step 8: Initialize Git

git init
git add .
git commit -m "Initial commit"

Your first snapshot is saved. All files listed in .gitignore (including .venv and .env) are excluded automatically.

Step 9: Create and push to GitHub

GitHub CLI (Recommended)
Traditional Git

# Create a private repository and push in one command
gh repo create my-awesome-project --private --source=. --remote=origin --push

# Or make it public
gh repo create my-awesome-project --public --source=. --remote=origin --push

If you don’t have GitHub CLI yet, install it:

brew install gh

winget install --id GitHub.cli

sudo apt install gh

Then authenticate: gh auth login

Go to github.com → + → New repository
Name it my-awesome-project, choose Public or Private
Do not add any files
Click Create repository

git remote add origin https://github.com/YOUR-USERNAME/my-awesome-project.git
git push -u origin main

Your project is now set up locally, tracked by Git, and backed up on GitHub.

The daily workflow

From this point on, your everyday routine is:

# Add packages as you discover you need them
uv add some-package

# Write code...

# Commit and push your changes
git add .
git commit -m "Add weather data fetch function"
git push

Prefer clicking to typing? VS Code’s Source Control panel (Ctrl/Cmd + Shift + G) lets you stage, commit, and push entirely with mouse clicks. The sync button in the status bar handles push and pull together.

Quick reference cheat sheet

Project creation (one time):

uv init project-name
cd project-name
code .
uv add requests pandas python-dotenv
echo "API_KEY=your-key" > .env
git init
git add .
git commit -m "Initial commit"
gh repo create project-name --private --source=. --remote=origin --push

Daily development:

uv add package-name         # Add a new dependency
uv run python script.py     # Run your code
git add .                   # Stage changes
git commit -m "message"     # Commit
git push                    # Sync to GitHub

What’s next?

You’ve completed the Python tooling and project setup track. Continue with the weather data analysis project to put everything into practice.

Weather data analysis project

Build a real-world data analysis project using APIs and visualization

Developer Tools

Environment & Secrets

Project Structure

Weather Project

Complete Python Project Setup: A Step-by-Step Guide

Step 1: Open your terminal

Step 2: Navigate to your projects folder

Step 3: Create the project with uv

Step 4: Open in VS Code

Step 5: Add your dependencies

Step 6: Test that everything works

Step 7: Set up environment variables

Step 8: Initialize Git

Step 9: Create and push to GitHub

The daily workflow

Quick reference cheat sheet

What’s next?

Weather data analysis project

​Step 1: Open your terminal

​Step 2: Navigate to your projects folder

​Step 3: Create the project with uv

​Step 4: Open in VS Code

​Step 5: Add your dependencies

​Step 6: Test that everything works

​Step 7: Set up environment variables

​Step 8: Initialize Git

​Step 9: Create and push to GitHub

​The daily workflow

​Quick reference cheat sheet

​What’s next?

Weather data analysis project

Step 1: Open your terminal

Step 2: Navigate to your projects folder

Step 3: Create the project with uv

Step 4: Open in VS Code

Step 5: Add your dependencies

Step 6: Test that everything works

Step 7: Set up environment variables

Step 8: Initialize Git

Step 9: Create and push to GitHub

The daily workflow

Quick reference cheat sheet

What’s next?