| | | |

PC → GitHub → Raspberry Pi: Python Project Deployment Workflow

Byadmin-hamid

Goal

Develop a project on a PC and store it in a Git repository (e.g. GitHub).
Deploy it on a Raspberry Pi by cloning the repository, installing dependencies, and running the application.
Keep a clean and repeatable workflow for updating the project from PC to Pi.

Intended workflow

PC (development) → GitHub repository (source of truth) → Raspberry Pi (execution)

We assume a Python project developed in Cursor and a GitHub repository, but the same workflow applies to other languages, tools, and environments.
Code is written, modified (and typically tested) on the PC, then committed and pushed to the repository.
The Raspberry Pi pulls the project from the repository and runs it locally.

Remember:

  • the repository is the reference point between machines
  • changes should flow from PC → repository → Pi
  • avoid modifying tracked files directly on the Pi unless intentional

PC side — prepare and push the project

We assume you already have a project folder on your PC, and that Git is already installed.
Start by opening a terminal in the project folder and initializing a local Git repository:

git init
git branch -M main

Create a .gitignore file so that generated files and local-only files are not committed:

.venv/
__pycache__/
*.pyc
.env

If your project uses Python, generate requirements.txt from the currently installed packages of the active environment:

pip freeze > requirements.txt

Then add the remote repository:

git remote add origin https://github.com/<username>/<repository>.git

Now create the first commit and push it:

git add .
git commit -m "Initial commit"
git config --global credential.helper store
git push -u origin main

When GitHub asks for authentication, use your GitHub username and a fine-grained Personal Access Token, not your GitHub account password. GitHub documents that Git over HTTPS uses tokens instead of account passwords, and fine-grained PATs are the current recommended token type.

Remember:

  • .gitignore prevents new matching files from being tracked, but it does not automatically untrack files that were already committed. Git’s documentation is explicit about this behavior.
  • pip freeze > requirements.txt records the packages currently installed in the active Python environment, so the Raspberry Pi can later recreate that environment.

What if it does not work?

Push fails (Repository not found / Authentication failed)

These two messages are often related. In practice, this usually means either the remote URL is wrong, or authentication is failing.

First, verify the remote:

git remote -v

Then check:

  • the repository name and username are correct
  • the repository actually exists on GitHub
  • you are using a fine-grained PAT
  • the token has access to that repository

No credential prompt appears, or the Cursor / PowerShell terminal behaves strangely

Try forcing terminal prompting in the current PowerShell session:

$env:GIT_ASKPASS = ""
$env:GIT_TERMINAL_PROMPT = "1"

If this problem happens often, you can add those same lines to your PowerShell profile file ($PROFILE) so they are applied automatically in future sessions.

.gitignore does not seem to work

If a file was already committed before being added to .gitignore, Git will continue tracking it. Remove it from the index once, then commit that change:

git rm -r --cached .venv __pycache__
git commit -m "Stop tracking generated files"

git command not found

Verify first:

git --version

If the command is not found, install Git, then reopen the terminal and try again.

Raspberry Pi side — first deployment

On the Raspberry Pi, clone the repository into the desired folder and enter the project directory:

git clone https://github.com/<username>/<repository>.git
cd <repository>

Create a Python virtual environment and activate it:

python3 -m venv .venv
source .venv/bin/activate

Install the project dependencies from requirements.txt:

pip install --upgrade pip
pip install -r requirements.txt

Then run the application manually for the first test:

python main.py

Replace main.py with the actual entry point of your project.
For a web application, this may instead be something like:

uvicorn app.main:app --host 0.0.0.0 --port 8000

Remember:

  • the Raspberry Pi has its own Python environment, independent from the PC
  • cloning the repository copies the code, but not the installed Python packages
  • always test the application manually before setting up any service or auto-start mechanism

What if it does not work?

python3 -m venv .venv fails

The Python virtual environment module may not be installed. Install it, then try again:

sudo apt update
sudo apt install -y python3-venv

pip install -r requirements.txt fails

Possible causes include:

  • a package version that is not available for the Pi architecture
  • missing system libraries or build tools
  • a requirements file generated on the PC that includes packages not really needed on the Pi

Try reading the first error message carefully. In many cases, the solution is to install a missing system package with apt, then retry.

The application starts on the PC but not on the Pi

Check:

  • Python version differences
  • missing environment variables
  • file paths that assume Windows-style locations
  • missing Linux packages or permissions

Module not found / package missing

Make sure:

  • the virtual environment is activated
  • pip install -r requirements.txt completed successfully
  • requirements.txt was committed and pulled correctly from the repository

Updating the project

After the first deployment, the normal update flow remains the same: make changes on the PC, commit them, and push them to the repository.
On the Raspberry Pi, go to the project folder and pull the latest version:

git pull

If the update includes new or changed Python dependencies, activate the virtual environment and reinstall them:

source .venv/bin/activate
pip install -r requirements.txt

Then run the application again, or restart its service if it is managed by systemd or another supervisor.

Remember:

  • changes should normally be made on the PC, not directly on the Pi
  • after git pull, reinstall dependencies only if requirements.txt changed
  • test important updates manually before relying on automatic startup

What if it does not work?

git pull fails because of local changes

A common message is:

error: Your local changes to the following files would be overwritten by merge:
    requirements.txt
Please commit your changes or stash them before you merge.
Aborting

This means the Raspberry Pi has local modifications to tracked files, and Git is refusing to overwrite them.

First, inspect the local state:

git status

Then choose one of these paths:

Keep the local changes
Commit them before pulling:

git add .
git commit -m "Local changes on Pi"
git pull

Keep the local changes, but not as a commit yet
Stash them temporarily:

git stash
git pull
git stash pop

Discard the local changes
If the Pi should exactly match the repository version and the local edits are not needed:

git restore .
git pull

Use git restore . carefully, because it discards uncommitted changes in tracked files.

requirements.txt changed, but dependencies were not reinstalled

The code may pull successfully, but the application can still fail afterward if new packages are required.
If requirements.txt changed, activate the virtual environment and run:

source .venv/bin/activate
pip install -r requirements.txt

The application still behaves differently after pull

Check whether the update also depends on:

  • environment variables
  • external configuration files
  • system packages installed with apt
  • file or service permissions on the Pi

Similar Posts