> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi2day.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Complete Python Project Setup: A Step-by-Step Guide
> Follow this checklist to set up every new Python project correctly with uv, environment variables, Git, and a GitHub remote in under 10 minutes.
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
```bash macOS theme={null}
# Terminal app or iTerm
```
```powershell Windows theme={null}
# Terminal, Command Prompt, or PowerShell
```
## Step 2: Navigate to your projects folder
```bash theme={null}
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
```bash theme={null}
uv init my-awesome-project
```
`uv init` generates a complete starting structure:
```text theme={null}
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
```bash theme={null}
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 + ` ``):
```bash theme={null}
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:
```python theme={null}
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}")
```
```bash theme={null}
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):
```text theme={null}
# .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):
```text theme={null}
# .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
```bash theme={null}
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
```bash theme={null}
# 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:
```bash macOS theme={null}
brew install gh
```
```powershell Windows theme={null}
winget install --id GitHub.cli
```
```bash Linux (Debian/Ubuntu) theme={null}
sudo apt install gh
```
Then authenticate: `gh auth login`
1. Go to [github.com](https://github.com) → **+** → **New repository**
2. Name it `my-awesome-project`, choose Public or Private
3. **Do not** add any files
4. Click **Create repository**
```bash theme={null}
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:
```bash theme={null}
# 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):**
```bash theme={null}
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:**
```bash theme={null}
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.
Build a real-world data analysis project using APIs and visualization