← Retour aux tutoriels

Guide débutant : bien démarrer (pas à pas)

débutantguidetutorielbasesconseils

Guide débutant : bien démarrer (pas à pas)

Ce tutoriel s’adresse à une personne qui débute et qui veut mettre en place un environnement de travail propre, comprendre les bases du terminal, apprendre à installer des outils, utiliser Git, créer un petit projet, puis savoir déboguer et partager son travail.
Les exemples ci-dessous sont volontairement concrets, avec de vraies commandes à copier-coller.

Hypothèses : vous utilisez Windows, macOS ou Linux. Quand une commande diffère, je le précise.
Objectif : à la fin, vous saurez créer un projet, l’exécuter, le versionner, et éviter les pièges courants.

1) Comprendre l’environnement : OS, terminal, éditeur, dossiers

Avant d’installer quoi que ce soit, clarifions les éléments :

1.1 Installer un éditeur : Visual Studio Code

Téléchargez VS Code : https://code.visualstudio.com/

Ensuite, installez-le normalement.
Option utile : activer la commande code dans le PATH pour ouvrir VS Code depuis le terminal.

Test :

code --version

Si vous voyez une version, c’est bon.

2) Apprendre les bases du terminal (indispensable)

Le terminal peut sembler intimidant, mais il est surtout précis et reproductible : une commande = un résultat.

2.1 Ouvrir le terminal

2.2 Savoir où vous êtes : pwd / cd

pwd

Sur Windows PowerShell, l’équivalent est :

pwd
cd Documents

Remonter d’un niveau :

cd ..

Aller directement dans votre dossier personnel :

cd ~

2.3 Lister les fichiers : ls / dir

ls
ls -la
dir

2.4 Créer dossiers/fichiers : mkdir, touch, redirections

Créer un dossier :

mkdir projets
cd projets

Créer un fichier vide :

touch README.md
New-Item README.md -ItemType File

Écrire du texte dans un fichier (attention : écrase le contenu) :

echo "Bonjour" > fichier.txt

Ajouter à la fin (sans écraser) :

echo "Ligne suivante" >> fichier.txt

Afficher un fichier :

cat fichier.txt

Sur Windows PowerShell :

Get-Content fichier.txt

2.5 Comprendre les chemins

Exemples :

3) Installer un langage + un gestionnaire de versions (Python conseillé)

Pour débuter, Python est excellent : simple, très utilisé, et pratique pour apprendre.

3.1 Vérifier si Python est déjà installé

python3 --version

Sur Windows, parfois :

python --version

Si la commande n’existe pas ou si la version est très ancienne, installez Python.

3.2 Installer Python (selon OS)

Installer Homebrew (macOS)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Puis :

brew update
brew install python
python3 --version

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install -y python3 python3-venv python3-pip
python3 --version

4) Créer un projet propre : dossier, venv, dépendances

L’erreur la plus fréquente chez les débutants : installer des bibliothèques “globalement” et casser l’environnement.
Solution : utiliser un environnement virtuel (venv) par projet.

4.1 Créer le dossier du projet

mkdir -p ~/projets/bonjour-python
cd ~/projets/bonjour-python

Sur Windows PowerShell (chemin typique) :

mkdir $HOME\projets\bonjour-python
cd $HOME\projets\bonjour-python

4.2 Créer et activer un environnement virtuel

macOS/Linux :

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

Windows PowerShell :

python -m venv .venv
.venv\Scripts\Activate.ps1

Vous devriez voir le nom de l’environnement dans le prompt (souvent (.venv)).

4.3 Mettre à jour pip

python -m pip install --upgrade pip
pip --version

4.4 Créer un script Python

Créez main.py :

cat > main.py << 'EOF'
def main():
    print("Bonjour ! Projet Python prêt.")

if __name__ == "__main__":
    main()
EOF

Sur Windows PowerShell, vous pouvez utiliser un éditeur (VS Code) ou :

@'
def main():
    print("Bonjour ! Projet Python prêt.")

if __name__ == "__main__":
    main()
'@ | Set-Content main.py

Exécuter :

python main.py

5) Installer une dépendance réelle et la figer

On va installer une bibliothèque utile, par exemple requests (HTTP).

pip install requests

Tester rapidement dans un fichier http_test.py :

cat > http_test.py << 'EOF'
import requests

r = requests.get("https://httpbin.org/get", timeout=10)
print("Status:", r.status_code)
print("Clés JSON:", list(r.json().keys()))
EOF
python http_test.py
EOF

Si vous êtes derrière un proxy ou un réseau restrictif, l’appel peut échouer. Ce n’est pas “vous”, c’est le réseau. Dans ce cas, testez avec une URL interne ou un autre endpoint.

5.1 Figer les dépendances : requirements.txt

Pour partager un projet, il faut que quelqu’un d’autre puisse installer les mêmes dépendances.

pip freeze > requirements.txt
cat requirements.txt

Plus tard, sur une autre machine :

pip install -r requirements.txt

6) Git : versionner votre projet (et éviter les catastrophes)

Git permet de :

6.1 Installer Git

Vérifier :

git --version

Si absent :

brew install git
sudo apt update
sudo apt install -y git

6.2 Configurer Git (une fois)

git config --global user.name "Votre Nom"
git config --global user.email "vous@example.com"
git config --global init.defaultBranch main

Vérifier :

git config --global --list

6.3 Initialiser un dépôt Git

Dans votre projet :

cd ~/projets/bonjour-python
git init

Voir l’état :

git status

6.4 Créer un .gitignore (très important)

On ne versionne pas :

Créer .gitignore :

cat > .gitignore << 'EOF'
.venv/
__pycache__/
*.pyc
.DS_Store
EOF

6.5 Ajouter et committer

git add .
git commit -m "Initialisation du projet Python (venv, script, requirements)"

Afficher l’historique :

git log --oneline --decorate

7) Ouvrir le projet dans VS Code et configurer l’interpréteur

Depuis le dossier du projet :

code .

Dans VS Code :

Pourquoi c’est crucial : VS Code doit utiliser le Python du projet, pas celui du système, sinon vous aurez des erreurs du type “module not found”.

8) Ajouter une structure minimale “propre”

Même pour un petit projet, une structure claire aide.

Proposition :

bonjour-python/
  main.py
  http_test.py
  requirements.txt
  README.md
  .gitignore

Ajoutons un README.md utile :

cat > README.md << 'EOF'
# bonjour-python

Petit projet de démarrage Python.

## Prérequis
- Python 3.x
- (Optionnel) Git

## Installation
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Exécution

python main.py

EOF


> Note : dans un vrai projet, on détaillerait aussi Windows (PowerShell) et les versions exactes.

Commit :

```bash
git add README.md
git commit -m "Ajout d'un README avec instructions"

9) Débogage : comprendre les erreurs fréquentes

9.1 “command not found” / “n’est pas reconnu…”

Cela signifie que :

Exemples :

Vérifiez :

9.2 “ModuleNotFoundError: No module named ‘requests’”

Cause : vous exécutez le script avec un Python qui n’a pas la dépendance.

Diagnostic :

which python
python -c "import sys; print(sys.executable)"
pip -V

Sur Windows PowerShell :

where python
python -c "import sys; print(sys.executable)"
pip -V

Solution :

pip install requests

9.3 Erreurs réseau (timeout, DNS, proxy)

Si requests.get(...) échoue :

Exemple avec timeout plus grand :

requests.get("https://httpbin.org/get", timeout=30)

10) Publier sur GitHub (optionnel mais recommandé)

10.1 Créer un dépôt sur GitHub

10.2 Ajouter un remote et pousser

Exemple HTTPS :

git remote add origin https://github.com/votre-compte/bonjour-python.git
git branch -M main
git push -u origin main

Vérifier :

git remote -v

Si GitHub demande une authentification, utilisez un token (PAT) ou configurez SSH. GitHub n’accepte plus le mot de passe sur HTTPS.

11) Bonnes pratiques simples (qui font une grande différence)

11.1 Un projet = un environnement

Ne réutilisez pas un .venv pour plusieurs projets.
Chaque projet doit avoir ses dépendances isolées.

11.2 Des commits petits et descriptifs

Au lieu d’un seul gros commit “tout”, faites :

11.3 Toujours vérifier git status

Avant un commit ou un push :

git status

Cela évite d’ajouter par erreur des fichiers lourds, secrets, ou inutiles.

11.4 Ne jamais committer des secrets

Ne mettez pas dans Git :

Si vous devez utiliser des variables d’environnement, créez un fichier .env.example (sans secrets) et ignorez .env.

Ajout au .gitignore :

echo ".env" >> .gitignore
git add .gitignore
git commit -m "Ignore le fichier .env"

12) Mini-exercice guidé : transformer le script en petit outil CLI

Objectif : un script qui affiche un message personnalisé via argument.

12.1 Modifier main.py

cat > main.py << 'EOF'
import sys

def main():
    if len(sys.argv) < 2:
        print("Usage: python main.py <prenom>")
        raise SystemExit(2)

    prenom = sys.argv[1]
    print(f"Bonjour, {prenom} !")

if __name__ == "__main__":
    main()
EOF

Tester :

python main.py
python main.py Alice

12.2 Commit

git add main.py
git commit -m "Ajout d'un argument CLI (prenom) au script"

13) Aller plus loin (prochaines étapes logiques)

Quand vous serez à l’aise avec ce guide, voici des progressions naturelles :

  1. Tests automatisés avec pytest
    Installation :

    pip install pytest

    Lancer :

    pytest

  2. Formatage avec ruff (rapide et moderne)

    pip install ruff
ruff check .
ruff format .

  3. Packaging (pyproject.toml) et structure src/
    Utile quand le projet grandit.

  4. CI/CD (GitHub Actions)
    Pour exécuter tests/linters automatiquement à chaque push.

14) Récapitulatif des commandes clés

Navigation / fichiers

pwd
ls -la
cd ..
mkdir projets
touch README.md
cat fichier.txt

Python / venv

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests
pip freeze > requirements.txt
python main.py

Git

git init
git status
git add .
git commit -m "message"
git log --oneline
git remote add origin <url>
git push -u origin main

Conclusion

Vous avez maintenant un socle solide : terminal, structure de projet, environnement virtuel, dépendances, Git, et méthodes de diagnostic.
Le point le plus important n’est pas de connaître “toutes les commandes”, mais de maîtriser le cycle complet :

  1. créer un projet propre,
  2. exécuter et tester,
  3. versionner,
  4. partager,
  5. corriger quand ça casse.

Si vous me dites votre OS (Windows/macOS/Linux) et votre objectif (web, data, automatisation, etc.), je peux proposer une suite “pas à pas” adaptée avec un projet concret.

Tutoriels associés

Comment analyser et optimiser vos données avec pandas Comment lancer vos premières apps avec Docker facilement Comment utiliser CSS Flexbox pour un design responsive