> ## 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 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

<Steps>
  <Step title="Open your terminal">
    Open your system terminal:

    * **macOS:** Terminal or iTerm2
    * **Windows:** Windows Terminal, PowerShell, or Command Prompt
    * **Linux:** Your preferred terminal emulator
  </Step>

  <Step title="Navigate to your projects folder">
    <CodeGroup>
      ```bash macOS / Linux theme={null}
      cd ~/PythonProjects
      ```

      ```bash Windows theme={null}
      cd C:\Users\YourName\Documents\PythonProjects
      ```
    </CodeGroup>

    <Tip>
      Keep all your Python projects in one dedicated folder. It makes everything easier to find and back up.
    </Tip>
  </Step>

  <Step title="Create the project with uv">
    ```bash theme={null}
    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
    ```

    <Note>
      The `.venv` folder and `uv.lock` are created automatically when you first run `uv add`. They do not exist yet at this stage.
    </Note>
  </Step>

  <Step title="Open the project in VS Code">
    ```bash theme={null}
    code .
    ```

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

    <Note>
      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**.
    </Note>
  </Step>

  <Step title="Add your project's packages">
    Open the integrated terminal in VS Code (`` Ctrl + ` ``) and install what your project needs:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Test your setup">
    Edit `main.py` to verify everything works:

    ```python theme={null}
    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:

    ```bash theme={null}
    uv run python main.py
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file for your secrets (API keys, database URLs, etc.):

    ```bash theme={null}
    # .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:

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

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Initialise Git">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Create a GitHub repository">
    <Tabs>
      <Tab title="GitHub CLI (recommended)">
        ```bash theme={null}
        # 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:

        <CodeGroup>
          ```bash macOS theme={null}
          brew install gh
          ```

          ```bash Windows theme={null}
          winget install --id GitHub.cli
          ```

          ```bash Linux (Debian/Ubuntu) theme={null}
          sudo apt install gh
          ```
        </CodeGroup>

        Then authenticate:

        ```bash theme={null}
        gh auth login
        ```
      </Tab>

      <Tab title="GitHub website">
        1. Go to [github.com](https://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:

        ```bash theme={null}
        git remote add origin https://github.com/YOUR-USERNAME/my-awesome-project.git
        git push -u origin main
        ```
      </Tab>
    </Tabs>

    Your project is now backed up on GitHub and ready for collaboration.
  </Step>
</Steps>

## Your daily development workflow

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

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

## Quick reference: the full setup in one block

```bash theme={null}
# ── 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

<Card title="Course Resources" icon="compass" href="/getting-started/course-resources">
  Access all practice notebooks, exercise files, and real-world datasets for the course.
</Card>