Complete Python Project Setup with uv: Step-by-Step

Follow a step-by-step end-to-end guide to create, configure, and push a Python project using uv, VS Code, environment variables, Git, and GitHub.

This page brings everything together into a repeatable workflow you can follow for every new Python project. By the end of this walkthrough, you will have a project that is set up locally with uv, tracked by Git, backed up on GitHub, and configured with proper environment variable handling. This is the real-world professional setup used for Python and AI development projects.

The complete workflow at a glance

1. Open your terminal

   Open your system terminal:

   • macOS: Terminal or iTerm2
   • Windows: Windows Terminal, PowerShell, or Command Prompt
   • Linux: Your preferred terminal emulator
2. Navigate to your projects folder

   macOS / Linux

   cd ~/PythonProjects
   

   Keep all your Python projects in one dedicated folder. It makes everything easier to find and back up.

3. Create the project with uv

   uv init my-awesome-project
   cd my-awesome-project
   

   uv creates this structure instantly:

   my-awesome-project/
   ├── .gitignore          # .venv, .env, __pycache__ are already excluded
   ├── .python-version     # Pins the Python version
   ├── pyproject.toml      # Project configuration and dependencies
   ├── README.md           # Project description
   └── main.py             # Example entry point
   

   The .venv folder and uv.lock are created automatically when you first run uv add. They do not exist yet at this stage.

4. Open the project in VS Code

   code .
   

   VS Code opens, the Python extension detects your project, and the virtual environment will be recognised automatically once you install packages.

   If code . does not work, install the VS Code CLI by opening VS Code, pressing Ctrl/Cmd + Shift + P, and running Shell Command: Install ‘code’ command in PATH.

5. Add your project's packages

   Open the integrated terminal in VS Code (Ctrl + `) and install what your project needs:

   uv add requests
   uv add pandas numpy
   uv add python-dotenv
   uv add ipykernel           # For interactive Python in VS Code
   

   After these commands, uv has:

   • Created .venv/ with all packages installed
   • Updated pyproject.toml with your declared dependencies
   • Generated uv.lock with exact reproducible versions

   Then select the virtual environment as your interpreter: press Ctrl/Cmd + Shift + P → Python: Select Interpreter → choose the .venv option.

6. Test your setup

   Edit main.py to verify everything works:

   import requests
   from dotenv import load_dotenv
   import os
   
   # Load environment variables from .env
   load_dotenv()
   
   print("✅ Packages imported successfully!")
   
   # Test environment variable access
   api_key = os.environ.get("API_KEY", "not-set")
   print(f"✅ API_KEY: {api_key}")
   
   # Test an HTTP request
   response = requests.get("https://api.github.com")
   print(f"✅ GitHub API status: {response.status_code}")
   

   Run it:

   uv run python main.py
   
7. Set up environment variables

   Create a .env file for your secrets (API keys, database URLs, etc.):

   # .env  — never commit this file
   API_KEY=your-secret-key-here
   DATABASE_URL=postgresql://localhost/mydb
   DEBUG=True
   

   Create a .env.example as a safe template to commit:

   # .env.example  — commit this so teammates know what variables are needed
   API_KEY=your-api-key-here
   DATABASE_URL=your-database-url
   DEBUG=True
   

   Never commit your actual .env file to version control. It already appears in the .gitignore that uv created, but double-check before your first commit.

8. Initialise Git

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

   This creates your first Git snapshot. Your .venv/ and .env are already excluded by uv’s .gitignore.

9. Create a GitHub repository

   GitHub CLI (recommended)

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

   If you do not have the GitHub CLI installed:

   macOS

   brew install gh
   

   Then authenticate:

   gh auth login
   

   GitHub website

   1. Go to github.com and click + → New repository
   2. Name it my-awesome-project
   3. Set it to Private
   4. Do not initialise with any files
   5. Click Create repository
   6. Then run:

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

   Your project is now backed up on GitHub and ready for collaboration.

Your daily development workflow

After the initial setup, your day-to-day routine is simple:

# Add a new package when needed
uv add some-package

# Run your code
uv run python main.py

# Stage and commit your changes
git add .
git commit -m "Add feature: describe what changed"

# Push to GitHub
git push

You can do all Git operations through VS Code’s Source Control panel (Ctrl/Cmd + Shift + G) if you prefer clicking over typing. Stage files, write commit messages, and push — all without leaving the editor.

Quick reference: the full setup in one block

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

# ── Daily workflow ──────────────────────────────────────
uv add package-name          # Add packages as needed
uv run python script.py      # Run code
git add .                    # Stage changes
git commit -m "message"      # Commit
git push                     # Sync to GitHub

Pro tips for sustainable projects

1. Commit often — small, focused commits are easier to understand and revert than large ones
2. Write clear commit messages — “Fix login validation bug” is far more useful than “updates”
3. Keep secrets in .env — never hardcode API keys, passwords, or tokens in your source files
4. Update dependencies regularly — run uv sync --upgrade periodically to stay on secure, maintained versions
5. One virtual environment per project — never share environments across projects, even if they look similar

Course Resources

Access all practice notebooks, exercise files, and real-world datasets for the course.