WordPress : le plugin n’apparaît pas dans la liste des extensions

Vous venez de créer ou d’installer un plugin WordPress dans wp-content/plugins, mais il n’apparaît pas dans la liste des extensions. Aucun message clair. Rien dans l’admin. Le plugin joue à cache-cache, et il gagne.

Dans la plupart des cas, le problème vient d’un en-tête de plugin manquant ou invalide. WordPress ne liste pas les fichiers PHP au hasard : il cherche un fichier principal avec un commentaire d’en-tête contenant au minimum Plugin Name.

Mais ce n’est pas la seule cause possible. Un plugin peut aussi disparaître de la liste à cause d’un mauvais dossier, d’un fichier principal mal placé, d’une archive ZIP mal structurée, d’une erreur fatale PHP, d’un problème de permissions, d’un cache OPcache, ou d’un environnement multisite.

Kinsta: Premium Managed WordPress hosting

Vérifier l’en-tête du plugin

Un plugin WordPress doit contenir un fichier PHP principal avec un en-tête reconnu par WordPress. Le strict minimum ressemble à ceci :

<?php
/**
 * Plugin Name: Mon Plugin WordPress
 */Langage du code : HTML, XML (xml)

Sans ce champ Plugin Name, WordPress ne considère pas le fichier comme un plugin affichable dans l’administration.

Voici un en-tête plus complet et plus propre :

<?php
/**
 * Plugin Name:       Mon Plugin WordPress
 * Plugin URI:        https://www.example.com/
 * Description:       Description courte du plugin.
 * Version:           1.0.0
 * Requires at least: 6.0
 * Requires PHP:      8.1
 * Author:            Votre Nom
 * Author URI:        https://www.example.com/
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       mon-plugin-wordpress
 * Domain Path:       /languages
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;Langage du code : HTML, XML (xml)

Le champ indispensable reste Plugin Name. Les autres champs améliorent l’affichage, la compatibilité, les traductions, les mises à jour et la maintenance.

Le fichier principal doit être au bon endroit

WordPress scanne les plugins dans wp-content/plugins. Un plugin peut être un simple fichier PHP :

wp-content/plugins/mon-plugin.php

Ou un dossier contenant un fichier principal :

wp-content/plugins/mon-plugin/mon-plugin.php

Le problème apparaît souvent quand l’archive ZIP contient un dossier imbriqué inutile. Exemple cassé :

wp-content/plugins/mon-plugin/mon-plugin/mon-plugin.php

Dans ce cas, WordPress peut ne pas détecter le plugin comme prévu. Vérifiez donc la structure réelle :

find wp-content/plugins/mon-plugin -maxdepth 3 -type f -name "*.php" -printLangage du code : PHP (php)

Si vous voyez un dossier répété, déplacez le bon dossier au bon niveau.

WPEngine: Premium Managed WooCommerce hosting

Tester avec un plugin minimal

Pour isoler le problème, créez un plugin minimal directement dans wp-content/plugins :

cat > wp-content/plugins/test-plugin-visible.php <<'PHP'
<?php
/**
 * Plugin Name: Test Plugin Visible
 * Description: Plugin minimal pour tester la détection WordPress.
 * Version: 1.0.0
 */

defined( 'ABSPATH' ) || exit;
PHPLangage du code : PHP (php)

Rechargez ensuite la page Extensions dans l’administration WordPress. Si ce plugin apparaît, WordPress scanne bien le dossier des extensions. Le problème vient donc du plugin original.

Supprimez ensuite le fichier de test :

rm wp-content/plugins/test-plugin-visible.php

Lister les plugins avec WP-CLI

WP-CLI permet de vérifier rapidement ce que WordPress détecte :

wp plugin listLangage du code : PHP (php)

Pour afficher les chemins des plugins :

wp plugin list --fields=name,status,update,version,pathLangage du code : PHP (php)

Si le plugin n’apparaît pas dans WP-CLI, WordPress ne le reconnaît pas. Regardez alors l’en-tête, le chemin, le fichier principal et les erreurs PHP.

Si le plugin apparaît dans WP-CLI mais pas dans l’interface, regardez plutôt les droits utilisateur, le multisite, les filtres d’administration, ou un bug d’affichage côté admin.

Pour d’autres commandes utiles en audit WordPress, vous pouvez consulter l’article sur la liste des articles publiés avec WP-CLI.

Vérifier que le fichier commence bien par PHP

Le fichier principal doit commencer par une balise PHP valide. Évitez les caractères invisibles, espaces étranges ou BOM avant <?php.

Pour voir les premiers octets du fichier :

xxd -g 1 -l 16 wp-content/plugins/mon-plugin/mon-plugin.php

Un fichier PHP propre commence généralement par :

3c 3f 70 68 70

Ce qui correspond à :

<?phpLangage du code : HTML, XML (xml)

Si vous voyez ef bb bf avant <?php, le fichier contient probablement un BOM UTF-8. Certains environnements le tolèrent, d’autres moins. Dans le doute, enregistrez le fichier en UTF-8 sans BOM.

Le plus lu : Digsby, le client de messagerie instantanée multi-protocoles

Vérifier les erreurs PHP

Un plugin peut ne pas apparaître correctement ou casser la page des extensions si son fichier principal déclenche une erreur fatale pendant le scan.

Vérifiez la syntaxe PHP du fichier principal :

php -l wp-content/plugins/mon-plugin/mon-plugin.php

Pour vérifier tous les fichiers PHP du plugin :

find wp-content/plugins/mon-plugin -type f -name "*.php" -print0 | xargs -0 -n1 php -lLangage du code : JavaScript (javascript)

Si une erreur apparaît, corrigez-la avant de chercher plus loin. Un plugin invalide côté PHP ne pourra pas être chargé proprement. WordPress aime les en-têtes propres, mais il aime aussi le PHP qui compile. Exigeant, le garçon.

Activer le debug log WordPress

Sur un environnement de test, activez temporairement le journal de debug dans wp-config.php :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', '0' );Langage du code : JavaScript (javascript)

Rechargez ensuite la page des extensions, puis consultez le log :

tail -n 100 wp-content/debug.log

Si votre plugin déclenche une erreur fatale, un avertissement critique ou une dépendance manquante, le log donnera souvent la piste exacte.

Vérifier les permissions du plugin

WordPress doit pouvoir lire le dossier et les fichiers du plugin. Vérifiez les permissions :

ls -lah wp-content/plugins
ls -lah wp-content/plugins/mon-plugin

En général, les dossiers doivent être en 755 et les fichiers en 644 sur une installation WordPress classique :

find wp-content/plugins/mon-plugin -type d -exec chmod 755 {} \;
find wp-content/plugins/mon-plugin -type f -exec chmod 644 {} \;

Vérifiez aussi le propriétaire des fichiers :

namei -l wp-content/plugins/mon-plugin/mon-plugin.php

Si le serveur web ou PHP-FPM ne peut pas lire le fichier, WordPress ne pourra pas l’analyser correctement.

Pour une méthode détaillée sur les permissions WordPress, vous pouvez lire l’article sur les images WordPress en erreur 403. Le symptôme diffère, mais la logique serveur reste très proche.

Vérifier que le plugin n’est pas dans mu-plugins

Les extensions classiques se trouvent dans :

wp-content/plugins

Les extensions indispensables, ou must-use plugins, se trouvent dans :

wp-content/mu-plugins

Un plugin placé dans mu-plugins n’apparaît pas dans la liste classique des extensions activables/désactivables. Il apparaît dans une section dédiée, et il est chargé automatiquement.

Listez les mu-plugins avec WP-CLI :

wp plugin list --status=must-useLangage du code : PHP (php)

Si votre plugin est là, il n’est pas absent : il est simplement dans une autre catégorie.

Vérifier le multisite

En multisite, les plugins peuvent être visibles ou activés au niveau du réseau. Vérifiez si WordPress est en multisite :

wp core is-installed --network

Listez les plugins côté réseau :

wp plugin list --networkLangage du code : PHP (php)

Dans l’administration, allez dans Mes sites → Administration du réseau → Extensions. Un plugin peut ne pas apparaître là où vous le cherchez si vous êtes dans l’administration d’un sous-site au lieu de l’administration réseau.

Vérifier les dépendances Requires Plugins

Les versions récentes de WordPress supportent l’en-tête Requires Plugins. Il sert à déclarer des dépendances vers d’autres plugins WordPress.org.

/**
 * Plugin Name:       Mon Extension Dépendante
 * Requires Plugins:  woocommerce
 */Langage du code : JSON / JSON avec commentaires (json)

Une dépendance mal comprise ne devrait pas empêcher WordPress de détecter le plugin, mais elle peut empêcher son activation ou modifier son comportement dans l’admin. Vérifiez donc cet en-tête si votre plugin dépend d’un autre plugin.

Le plus lu : BleachBit : nettoyer Ubuntu, Linux et Windows pour regagner de l’espace disque

Vérifier la compatibilité PHP

Si votre plugin utilise PHP 8.1 ou 8.3 mais que le serveur tourne sous une version plus ancienne, il peut déclencher une erreur fatale dès que WordPress tente de lire ou charger le fichier.

Vérifiez la version PHP en ligne de commande :

php -v

Et la version PHP utilisée par WordPress :

wp eval 'echo PHP_VERSION;'Langage du code : JavaScript (javascript)

Ces deux valeurs peuvent différer. C’est fréquent sur les serveurs avec plusieurs versions de PHP. Si le plugin contient readonly, des enums, des types modernes ou des syntaxes récentes, assurez-vous que la version PHP réellement utilisée par WordPress les supporte.

Vider OPcache si le fichier a changé

Sur certains serveurs, OPcache peut garder une ancienne version d’un fichier PHP en mémoire. Si vous venez de corriger l’en-tête du plugin mais que WordPress ne le voit toujours pas, videz ou rechargez le cache PHP.

Sur un serveur avec PHP-FPM :

sudo systemctl reload php8.3-fpmLangage du code : CSS (css)

Adaptez la version à votre serveur :

systemctl list-units --type=service | grep phpLangage du code : PHP (php)

Sur un hébergement managé, utilisez l’outil de purge cache fourni par l’hébergeur.

Vérifier si une constante bloque les installations

Si le problème concerne plutôt le menu “Ajouter une extension” ou l’installation de plugins, vérifiez les constantes de configuration WordPress :

wp config list | grep -E 'DISALLOW_FILE_MODS|DISALLOW_FILE_EDIT'Langage du code : PHP (php)

La constante DISALLOW_FILE_MODS peut bloquer les installations, mises à jour et modifications de plugins depuis l’interface. Elle ne devrait pas empêcher WordPress de lister un plugin déjà présent, mais elle peut expliquer une confusion dans l’administration.

Vérifier les droits de l’utilisateur connecté

Un utilisateur sans capacité suffisante ne verra pas toujours le menu Extensions. Vérifiez le rôle du compte :

wp user list --fields=ID,user_login,rolesLangage du code : PHP (php)

Un administrateur standard doit avoir accès aux plugins. En multisite, seul le super-admin gère les extensions au niveau réseau.

Pour vérifier les super-admins en multisite :

wp super-admin listLangage du code : JavaScript (javascript)

Vérifier l’option active_plugins

WordPress stocke les plugins actifs dans l’option active_plugins. Si un plugin a été déplacé, renommé ou supprimé, WordPress peut le désactiver ou signaler que le fichier n’existe plus.

wp option get active_plugins --format=jsonLangage du code : JavaScript (javascript)

Vous y verrez des valeurs du type :

mon-plugin/mon-plugin.php

Si vous changez le nom du dossier ou du fichier principal, le slug du plugin change aussi. WordPress considère alors qu’il s’agit d’un autre plugin.

Cas fréquent : mauvais nom de fichier principal

WordPress peut détecter un plugin même si le fichier principal ne porte pas exactement le même nom que le dossier. Mais pour la maintenance, les mises à jour et la lisibilité, gardez une convention simple :

wp-content/plugins/mon-plugin/mon-plugin.php

Évitez les structures confuses :

wp-content/plugins/mon-plugin/index.php
wp-content/plugins/mon-plugin/plugin.php
wp-content/plugins/mon-plugin/includes/main.php

Elles peuvent fonctionner, mais elles compliquent le diagnostic. Et quand un problème arrive, la simplicité est une forme de politesse.

Cas fréquent : l’archive ZIP contient le mauvais niveau

Quand vous installez un plugin manuellement, vérifiez l’archive ZIP avant de l’envoyer sur le serveur.

Structure correcte :

mon-plugin.zip
└── mon-plugin
    ├── mon-plugin.php
    ├── readme.txt
    └── includesLangage du code : CSS (css)

Structure problématique :

mon-plugin.zip
└── build
    └── mon-plugin
        ├── mon-plugin.php
        ├── readme.txt
        └── includesLangage du code : CSS (css)

Après extraction, le dossier directement placé dans wp-content/plugins doit être celui qui contient le fichier principal du plugin.

Le plus lu : PHP : résoudre l'erreur "assigning the return value of new by reference is deprecated"

Cas fréquent : plugin incomplet après transfert FTP

Un transfert FTP interrompu peut laisser un plugin incomplet. Le dossier existe, mais le fichier principal manque, ou certains fichiers n’ont pas été envoyés.

Vérifiez rapidement :

find wp-content/plugins/mon-plugin -type f | wc -l
find wp-content/plugins/mon-plugin -type f -name "*.php" -printLangage du code : PHP (php)

Si vous avez un doute, supprimez le dossier et réinstallez proprement depuis une archive saine.

Si WordPress demande des identifiants FTP ou échoue pendant une mise à jour, l’article sur l’erreur ftp_nlist() expects parameter 1 to be resource complète bien ce diagnostic.

Créer un plugin WordPress minimal et propre

Voici une base saine pour un plugin moderne compatible PHP 8.3+ :

<?php
/**
 * Plugin Name:       Sky Example Plugin
 * Plugin URI:        https://www.skyminds.net/
 * Description:       Exemple minimal de plugin WordPress correctement détecté.
 * Version:           1.0.0
 * Requires at least: 6.0
 * Requires PHP:      8.1
 * Author:            Matt Biscay
 * Author URI:        https://www.skyminds.net/
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       sky-example-plugin
 * Domain Path:       /languages
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;Langage du code : HTML, XML (xml)

Placez-le ici :

wp-content/plugins/sky-example-plugin/sky-example-plugin.php

Rechargez ensuite Extensions. Le plugin doit apparaître dans la liste.

Checklist de diagnostic

Vérifier que le plugin est dans wp-content/plugins.
Vérifier que le fichier principal contient Plugin Name.
Vérifier que le fichier commence par <?php.
Vérifier qu’il n’y a pas de BOM avant la balise PHP.
Vérifier la structure du dossier après extraction du ZIP.
Tester la syntaxe avec php -l.
Lire wp-content/debug.log.
Vérifier les permissions et le propriétaire des fichiers.
Vérifier que le plugin n’est pas dans mu-plugins.
Vérifier le contexte multisite.
Vérifier la version PHP utilisée par WordPress.
Vider OPcache ou recharger PHP-FPM après correction.
Lister les plugins avec wp plugin list.

Commandes utiles

Lister les plugins détectés :

wp plugin listLangage du code : PHP (php)

Lister les fichiers PHP du plugin :

find wp-content/plugins/mon-plugin -type f -name "*.php" -printLangage du code : PHP (php)

Tester la syntaxe PHP :

php -l wp-content/plugins/mon-plugin/mon-plugin.php

Tester tous les fichiers PHP :

find wp-content/plugins/mon-plugin -type f -name "*.php" -print0 | xargs -0 -n1 php -lLangage du code : JavaScript (javascript)

Vérifier les premiers octets du fichier :

xxd -g 1 -l 16 wp-content/plugins/mon-plugin/mon-plugin.php

Lire les dernières erreurs WordPress :

tail -n 100 wp-content/debug.log

Vérifier les permissions :

namei -l wp-content/plugins/mon-plugin/mon-plugin.php

Vérifier les mu-plugins :

wp plugin list --status=must-useLangage du code : PHP (php)

Vérifier PHP côté WordPress :

wp eval 'echo PHP_VERSION;'Langage du code : JavaScript (javascript)

Conclusion

Si un plugin WordPress n’apparaît pas dans la liste des extensions, commencez par vérifier son en-tête. Le champ Plugin Name est indispensable : sans lui, WordPress ne sait pas qu’il regarde un plugin.

Ensuite, vérifiez le chemin du fichier principal, la structure du dossier, la syntaxe PHP, les permissions, la version PHP, le multisite et les mu-plugins. Dans la majorité des cas, le problème se trouve dans l’un de ces points.

La bonne nouvelle : une fois le diagnostic posé, la correction est souvent simple. WordPress ne cache pas les plugins par caprice. Il attend juste qu’ils se présentent correctement. Comme tout le monde, finalement.

Sources

Report a typo

Facebook Tweet Pin LinkedIn

WordPress : pourquoi mon plugin n’apparaît pas dans la liste des extensions ?