Ir al contenido

Configuration de Python et .venv dans VS Code

Dépannage des interprètes et des environnements virtuels à l'aide de VS Code sous les systèmes Windows.

0vues

Ce guide fournit la procédure technique définitive pour diagnostiquer, configurer et déployer des environnements de développement Python dans Visual Studio Code sous Windows. Il couvre tout, de l'affectation correcte des interprètes globaux (y compris les chemins non standard de winget ou du Microsoft Store) jusqu'à l'automatisation et l'installation de dépendances dans des environnements isolés (.venv).


Pour garantir un environnement de développement prévisible, il est essentiel de séparer l'interface utilisateur du moteur d'exécution et des paquets de dépendances de chaque projet.

  • Visual Studio Code (UI/Éditeur) : Fonctionne strictement comme un éditeur de texte avancé et un environnement de développement intégré. Il n'inclut pas de moteur Python intégré ; au lieu de cela, il délègue l'exécution du code à un interprète externe.
  • Python Engine (python.exe) : C'est le binaire responsable du traitement et de l'interprétation des instructions du code. Il s'exécute directement sur le système ou au sein de sous-environnements.

Environnement Global vs Environnement Virtuel (.venv)

Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»
  • Python Global: Correspond à l'installation de base du système. Agit comme un modèle initial et ne doit pas être modifié avec des packages externes pour éviter les collisions de dépendances entre différents projets.
  • Environnements virtuels (.venv): Ce sont des sous-répertoires isolés qui encapsulent leur propre binaire Python et leur arbre de dépendances (site-packages ).
┌──────────────────────────────────────────────────────────┐
│                   Sistema Operativo                      │
│   (Python Global - Instalación base libre de paquetes)   │
└────────────────────────────┬─────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
   ┌────────────────────┐        ┌────────────────────┐
   │    Proyecto A      │        │    Proyecto B      │
   │  (.venv A - Aislado)│        │  (.venv B - Aislado)│
   │  - Pandas v1.0     │        │  - Pandas v2.0     │
   │  - Requests        │        │  - Gemini API      │
   └────────────────────┘        └────────────────────┘

2. Procédure de configuration étape par étape

Sección titulada «2. Procedimiento de Configuración Paso a Paso»

Suivez strictement l'ordre suivant pour vous assurer que votre espace de travail initialise et exécute Python sans erreurs de dépendances.

Étape 1 : Installation de l'extension officielle

Sección titulada «Paso 1: Instalación de la Extensión Oficial»
  1. Accédez à l'onglet Extensions dans VS Code (Ctrl + Shift + X).
  2. Recherchez l'extension officielle Python développée par Microsoft.
  3. Appuyez sur Installer. Cette extension permet les capacités de débogage, IntelliSense et de gestion dynamique des interpréteurs dans l'éditeur.

Étape 2 : Localisation de l'interprète global (cas de winget)

Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»

Lorsque Python est installé via des gestionnaires de paquets tels que winget ou le Microsoft Store, il est fréquent que l'installateur n'enregistre pas l'exécutable dans les chemins système standards (PATH). Pour localiser votre exécutable de base :

  1. Ouvrez un terminal de commandes sur votre système (CMD ou PowerShell).
  2. Exécutez la commande de recherche suivante :
Ventana de terminal
where.exe python
  1. Le terminal retournera le chemin absolu vers l'exécutable actif. Par exemple : C:\Program Files\Python312\python.exe ou C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Conservez ce chemin.

Étape 3 : Initialisation de l'environnement virtuel (.venv)

Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»

Pour éviter les erreurs ou les boîtes de dialogue bloquantes dans les menus intégrés de VS Code, créez l'environnement directement depuis le terminal de l'éditeur :

  1. Ouvrez un terminal intégré dans VS Code (Ctrl + Ñ ou Ctrl + ~).
  2. Exécutez le module standard d'environnement virtuel en pointant vers le nom du répertoire .venv :
Ventana de terminal
python -m venv .venv
  1. Une fois l'exécution terminée, un nouveau répertoire .venv sera créé à la racine de votre espace de travail.

Étape 4 : Liaison de l'interpréteur VS Code avec l'environnement virtuel

Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»

Créer le sous-répertoire .venv n'active pas la connexion dans l'éditeur. Vous devez forcer VS Code à utiliser l'interprète nouvellement créé :

  1. Assurez-vous d'avoir au moins un fichier avec l'extension .py ouvert et sélectionné dans l'éditeur VS Code (cela active le moteur contextuel de Python).
  2. Ouvrez la palette de commandes en utilisant Ctrl + Shift + P.
  3. Tapez et sélectionnez Python: Select Interpreter (Python : Sélectionner l'interprète).
  4. L'éditeur présentera une liste. Sélectionnez l'option qui pointe directement vers votre environnement local. Elle est généralement indiquée comme recommandée :
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. Vérification de l'état : Observez le coin inférieur droit de la barre d'état de VS Code.
    • ✕ Chemin incorrect : Affiche Python 3.x.x (utilise le binaire du système global).
    • ✓ Chemin correct : Affiche Python 3.x.x ('.venv') (l'environnement est correctement lié).

Étape 5 : Activation de la console et installation des dépendances

Sección titulada «Paso 5: Activación de la Consola e Instalación de Dependencias»

Une fois l'interpréteur lié dans l'éditeur, chaque nouveau terminal ouvert héritera automatiquement de l'environnement virtuel actif.

  1. Ouvrez un nouveau terminal intégré (Ctrl + Ñ).
  2. Validez que l'invite de commandes affiche le préfixe d'activation à l'extrême gauche :
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Installez les bibliothèques nécessaires du projet directement dans votre environnement isolé :
Ventana de terminal
pip install google-generativeai requests pandas

SymptômeCause racineSolution
Le menu intégré Create Environment demande de saisir un chemin manuellement et se bloque.VS Code ne localise pas automatiquement l'installation de base de Python dans le PATH du système (cas habituel pour les installations via winget).*Annulez la boîte de dialogue intégrée. Suivez l'Étape 3 de ce guide pour créer l'environnement manuellement via le terminal avec python -m venv .venv.
Erreur ModuleNotFoundError: No module named '<libreria>' lors de l'appui sur 'Play'.Le code est exécuté par un interpréteur différent de celui qui contient les paquets installés (généralement le global).1. Vérifiez la barre inférieure droite de VS Code pour confirmer que l'interpréteur ('.venv') est bien lié.
2. Si ce n'est pas le cas, répétez l'étape 4 (Select Interpreter).
Le terminal n'affiche pas le préfixe (.venv) à l'ouverture.La console actuelle ne s'est pas mise à jour après la configuration de l'interpréteur ou a des politiques d'exécution restreintes dans PowerShell.1. Fermez tous les terminaux actifs avec l'icône de la corbeille dans le panneau inférieur.
2. Ouvrez un tout nouveau terminal (Ctrl + Ñ). Le script d'activation s'exécutera automatiquement.
Le sélecteur de version Python n'apparaît pas dans la barre d'état de VS Code.L'éditeur n'a pas chargé les services contextuels de Python car aucun fichier de code n'est ouvert.Ouvrez n'importe quel fichier avec l'extension .py dans votre éditeur principal pour forcer l'initialisation de l'extension Microsoft.