PrestaShop folder structure explained: what every directory does and when you need it

Last reviewed June 2026, verified against PrestaShop 1.6, 1.7, 8.x and 9.x. The directories below exist in all three; the main difference is how much has moved into /src/ (Symfony) and that PrestaShop 9 ships Hummingbird instead of Classic. Version-specific differences are flagged in the tables at the end.

Why Understanding the Folder Structure Matters

PrestaShop is a large application. A typical installation contains over 30,000 files across hundreds of directories. Most store owners never need to look at the filesystem. But if you develop modules, customize themes, debug issues, or manage your own server, knowing which directory does what saves hours of searching and prevents costly mistakes.

This guide covers the most important directories in a PrestaShop 1.7.x, 8.x, or 9.x installation. We start with the directories you will interact with most and work down to the ones you should leave alone.

/modules/ -- The Heart of PrestaShop Customization

This is the directory you will interact with most. Every module -- whether installed from the marketplace, uploaded as a ZIP, or developed custom -- lives here as a subdirectory.

modules/
  ps_emailsubscription/       -- PrestaShop native module
  mprcheckoutrevolution/      -- third-party module
  mymodule/                   -- your custom module
    mymodule.php              -- main module file (required)
    config.xml                -- cached module metadata
    views/
      templates/              -- Smarty templates
      css/                    -- stylesheets
      js/                     -- JavaScript
    controllers/
      front/                  -- front office controllers
      admin/                  -- admin controllers
    sql/                      -- install/upgrade SQL
    upgrade/                  -- version upgrade scripts
    translations/             -- translation files
    vendor/                   -- Composer dependencies

Key rules:

• The main PHP file must have the exact same name as the directory: modules/mymodule/mymodule.php
• The class name inside must match too: class Mymodule extends Module
• Never edit native PS modules (prefixed ps_) -- updates will overwrite your changes. Use hooks, overrides, or theme template overrides instead
• Module files must be owned by the web server user (www-data on most Linux setups) for uploads and cache generation to work

When you need this directory: Installing modules, developing modules, debugging module issues, checking which modules are installed, reviewing module source code.

/themes/ -- Visual Appearance and Templates

All front-office visual output is controlled by themes. Each theme is a subdirectory containing templates, assets, and configuration.

themes/
  classic/                    -- PS default theme (1.7/8)
    config/theme.yml          -- theme metadata, asset registration
    templates/                -- Smarty .tpl files
      catalog/                -- product, category pages
      checkout/               -- cart, checkout flow
      cms/                    -- CMS pages
      customer/               -- account pages
      _partials/              -- header, footer, notifications
      layouts/                -- page layout wrappers
    assets/
      css/                    -- compiled CSS
      js/                     -- compiled JS
      img/                    -- theme images (icons, placeholders)
    modules/                  -- module template overrides
  hummingbird/                -- PS 9 default theme
  my-child-theme/             -- your child theme

Key rules:

• Never edit the parent theme directly. Create a child theme that inherits from the parent and override only what you change.
• The active theme is set in Back Office > Design > Theme & Logo
• modules/ inside a theme takes priority over the module's own templates -- this is how themes customize module output
• PrestaShop 9 uses Hummingbird (Bootstrap 5, CSS layers). PrestaShop 1.7/8 uses Classic (Bootstrap 4).

When you need this directory: Customizing the store's appearance, creating child themes, overriding module templates, debugging template issues.

/config/ -- Configuration Files

Core configuration that PrestaShop reads on every request.

config/
  config.inc.php              -- NEVER EDIT: auto-generated, loads settings.inc.php
  settings.inc.php            -- database credentials, cookie key, PS version
  defines.inc.php             -- path constants, debug flags
  smarty.config.inc.php       -- Smarty template engine configuration
  autoload.php                -- Composer autoloader bootstrap

Key files:

• settings.inc.php -- Contains your database host, name, user, password, and the cookie encryption key. This file is generated during installation. Back this up. If you lose the cookie key, all existing customer sessions and employee sessions become invalid.
• defines.inc.php -- Where you toggle debug mode: set _PS_MODE_DEV_ to true for development (shows errors), false for production. Also contains _PS_CACHE_ENABLED_ and other runtime flags.

One thing that trips people up on PrestaShop 8 and 9: settings.inc.php may not exist. Newer installs store the same credentials in app/config/parameters.php instead, generated from the installer. If you are hunting for the database connection and config/settings.inc.php is missing, look in app/config/parameters.php. That is the modern home for the same values.

When you need this directory: Setting up a new installation, changing database credentials, toggling debug mode, troubleshooting connection issues.

/var/ -- Cache, Logs, and Temporary Files

PrestaShop's runtime data. This directory grows over time and can be safely cleared (except logs you want to keep).

var/
  cache/
    prod/                     -- production cache
      smarty/
        compile/              -- compiled Smarty templates
        cache/                -- Smarty output cache
      ContainerProdDebugProjectContainer.php  -- Symfony DI container
    dev/                      -- development cache (when _PS_MODE_DEV_ = true)
  logs/
    prod.log                  -- Symfony/PS error logs
    dev.log                   -- development mode logs

Key operations:

• Clear cache: rm -rf var/cache/prod/* -- the single most common fix for "I changed something but nothing happened"
• Alternatively: php bin/console cache:clear --env=prod
• The Smarty compile directory stores pre-compiled templates. If a template change doesn't appear, delete var/cache/prod/smarty/compile/*
• Check logs: var/logs/prod.log is the first place to look when something breaks. It contains PHP errors, Symfony exceptions, and module errors.

A caution for PrestaShop 9 specifically: the back office is a Symfony app with its own generated container under var/cache/prod/admin. A blind rm -rf var/cache/prod/* on a live PS 9 store can leave the admin with an incomplete container and throw 500 errors on the login page until the admin cache is rebuilt. On PS 9, prefer the console (php bin/console cache:clear --env=prod) over raw deletion, and clear it as the web-server user so the regenerated files have the right ownership.

When you need this directory: Clearing cache after changes, debugging errors via logs, freeing disk space on small servers.

/classes/ -- Core Business Logic (Legacy)

PrestaShop's original object model. Each file is a PHP class representing a business entity or utility.

classes/
  Product.php                 -- Product entity (attributes, prices, stock)
  Category.php                -- Category entity
  Cart.php                    -- Shopping cart logic
  Order.php                   -- Order entity
  Customer.php                -- Customer entity
  Module.php                  -- Base module class (install, hooks, config)
  Tools.php                   -- Utility functions (redirect, getValue, etc.)
  Db.php                      -- Database abstraction
  ObjectModel.php             -- Base ORM class
  shop/
    Shop.php                  -- Multi-shop logic
  tax/
    Tax.php                   -- Tax calculation
  stock/
    StockAvailable.php        -- Stock management

Key rules:

• Never edit these files directly. Use the /override/classes/ mechanism if you must change core behavior (but overrides have their own problems -- prefer hooks and modules).
• In PS 1.7+, many of these classes are being gradually replaced by Symfony services in /src/. Both systems coexist.
• ObjectModel is the base class for all entities. Understanding it is essential for module development -- it provides add(), update(), delete(), getFields(), and validation.

When you need this directory: Understanding how PrestaShop calculates prices, manages stock, processes orders. Reading (not editing) these files is how you learn the internal API.

/controllers/ -- Request Handling

Controllers process HTTP requests and render pages. PrestaShop has two sets: front office and admin.

controllers/
  front/
    ProductController.php     -- product page
    CategoryController.php     -- category listing
    CartController.php        -- cart operations
    OrderController.php       -- checkout steps
    CmsController.php         -- CMS pages
    SearchController.php      -- search results
  admin/
    AdminProductsController.php
    AdminOrdersController.php
    AdminCustomersController.php

Key rules:

• Front controllers extend FrontController. Admin controllers extend AdminController.
• In PS 1.7+, admin controllers are being migrated to Symfony (in /src/PrestaShopBundle/Controller/). Some admin pages use the new Symfony controllers, others still use the legacy ones here. Both coexist.
• Module controllers live in modules/yourmodule/controllers/, not here.

When you need this directory: Understanding how a specific page works, debugging page-level issues, finding which hooks are available on which page (controllers call Hook::exec()).

/src/ -- Symfony Layer (PS 1.7+)

The modern architecture layer. PrestaShop has been gradually migrating from the legacy /classes/ + /controllers/ pattern to Symfony since version 1.7.

src/
  Adapter/                    -- bridges between legacy and Symfony
  Core/
    Domain/                   -- CQRS commands and queries
      Product/
        Command/              -- CreateProduct, UpdateProduct, etc.
        Query/                -- GetProductForEditing, etc.
    Grid/                     -- admin list/grid definitions
    Form/                     -- admin form definitions
  PrestaShopBundle/
    Controller/               -- Symfony admin controllers
    Entity/                   -- Doctrine entities
    Form/                     -- Form types
    Translation/              -- Translation system
    Twig/                     -- Twig extensions for admin

Key rules:

• This directory grows with each PS version as more features migrate to Symfony
• The Adapter/ layer is critical -- it wraps legacy classes so Symfony services can use them
• In PS 9, most admin pages are fully Symfony. In PS 1.7/8, it is a mix of legacy and Symfony.
• Module developers rarely need to modify anything here -- interact with it through Symfony services registered in your module's services.yml

When you need this directory: Advanced module development using Symfony services, understanding the CQRS pattern for product/order management in PS 8+, contributing to PrestaShop core.

/override/ -- The Override System

PrestaShop's mechanism for modifying core behavior without editing core files.

override/
  classes/
    Product.php               -- overrides classes/Product.php
    Cart.php                  -- overrides classes/Cart.php
  controllers/
    front/
      ProductController.php   -- overrides controllers/front/ProductController.php
    admin/
      AdminProductsController.php

Key rules:

• Override classes extend the original and override specific methods
• Only one override per class is possible. If two modules try to override the same class, only the last one wins. This is why overrides are fragile -- module conflicts are guaranteed in active stores.
• After adding or removing overrides, regenerate the class index: delete var/cache/prod/class_index.php and clear cache
• PS 9 deprecates the override system. Prefer hooks, Symfony service decoration, or CQRS commands for new development.
• Overrides can cause mysterious bugs that are hard to trace. Always check override/ when debugging unexpected behavior.

When you need this directory: As a last resort when hooks don't provide the control you need. Always prefer hooks and module-based approaches. Read our Hooks & Overrides reference for the full picture.

/img/ -- Product and Content Images

img/
  p/                          -- product images (organized by ID digits)
    1/2/3/                    -- product ID 123's images
      123.jpg                 -- original
      123-home_default.jpg    -- resized for homepage
      123-large_default.jpg   -- resized for product page
  c/                          -- category images
  m/                          -- manufacturer/brand logos
  s/                          -- supplier logos
  cms/                        -- CMS page images (uploaded via editor)
  l/                          -- language flag icons
  tmp/                        -- temporary uploads

Key rules:

• Product images are stored with a path derived from the product ID digits: product 123 → img/p/1/2/3/. This distributes files across directories to avoid filesystem limits.
• Image regeneration (Back Office > Design > Image Settings > Regenerate) recreates all resized versions from originals. This can take hours on large catalogs.
• Back up this directory. Product images cannot be regenerated if originals are lost.
• WebP versions are generated alongside JPG/PNG in PS 8+ when enabled.

When you need this directory: Debugging missing product images, checking image quality, bulk image operations, server migration (this is often the largest directory by file count).

/app/ -- Symfony Application Kernel

app/
  AppKernel.php               -- Symfony kernel, registers bundles
  config/
    config.yml                -- Symfony service configuration
    parameters.php            -- auto-generated from settings.inc.php
    routing.yml               -- URL routing definitions
    security.yml              -- authentication/authorization
    services.yml              -- service container definitions

Key rules:

• AppKernel.php is the entry point for the Symfony side of PrestaShop. It registers all bundles including module bundles.
• config/routing.yml defines admin URL patterns. Module admin routes are registered separately via the module's own routing files.
• In PS 9, the kernel has been significantly refactored. parameters.php generation may differ.

When you need this directory: Advanced debugging of Symfony routing, service container issues, or authentication problems. Most developers never touch this directly.

/translations/ -- Core Translation Files

translations/
  default/                    -- default English strings
  en-US/                      -- US English
  fr-FR/                      -- French
  de-DE/                      -- German
    ShopTheme.fr-FR.xlf       -- front office translations
    AdminNavigation.fr-FR.xlf -- admin menu translations

Key rules:

• Core translations use XLIFF format (.xlf). Module translations use PHP arrays or XLIFF depending on the PS version.
• Translation packs are installed via Back Office > International > Translations or php bin/console prestashop:translation:export
• Database-stored translations (edited in the back office) take priority over file-based translations.

Directories You Should Never Modify

These directories are part of PrestaShop's core infrastructure. Editing them directly means your changes will be lost on update, and you risk breaking the entire installation:

• /vendor/ -- Composer dependencies (Symfony, Doctrine, etc.). Managed by composer install. Never edit.
• /bin/ -- Console commands (bin/console). Run them, don't edit them.
• /tools/ -- Build and maintenance scripts. Internal use.
• /install/ -- Installation wizard. Deleted after installation (should be, for security).
• /admin-dev/ (or your renamed admin folder) -- Admin entry point. Rename for security, but don't edit the files inside.
• /webservice/ -- REST API endpoint. Configured via back office, not by editing files.

Quick Reference: Where to Find What

On a live server, this quick audit tells you where the store has custom code before you touch anything:

find modules themes override -maxdepth 2 -type d | sort
find override -type f -name '*.php' -print
find themes -path '*/modules/*' -type f -name '*.tpl' -print
find var/logs -type f -mtime -3 -print

What Changes Between PS Versions

The overall trend is clear: PrestaShop is moving from the legacy architecture (/classes/ + /controllers/ + /override/) toward Symfony (/src/ + service decoration + CQRS). New module development should target the Symfony patterns where available, while maintaining backward compatibility with 1.7 through version-guarded code.

Frequently Asked Questions

Can I safely delete the whole var/ directory to free space?

Delete cache, not logs you still need, and never blindly wipe the admin cache on a live PrestaShop 9 store. Clearing var/cache/ is fine, PrestaShop rebuilds it on the next request. But on PS 9 the back office relies on a generated Symfony container under var/cache/prod/admin, and a raw delete can break the admin login with a 500 until that container is rebuilt. Use the back-office "Clear cache" button or php bin/console cache:clear --env=prod instead of rm -rf on production. Logs under var/logs/ are safe to delete but are often the only record of what went wrong, so archive before clearing.

I edited a template / a class but nothing changed on the site. Why?

Almost always cache. Smarty stores compiled templates under var/cache/prod/smarty/compile/, and PrestaShop also caches the Symfony container and class index. Clear the cache after editing templates or overrides. If it is a PHP class change and the file is on a server with OPcache, you may also need to reset OPcache (or restart PHP-FPM), because the old compiled bytecode can persist even after the cache directory is cleared.

Where do my changes actually live so they survive an upgrade?

Anything you want to keep through a core update belongs in /modules/ (your own modules), your child theme under /themes/, or, as a last resort, /override/. Editing files under /classes/, /controllers/, /src/, the parent theme, or native ps_ modules means the next upgrade overwrites your work. The whole point of the override and module system is to keep your customizations out of the directories the upgrader replaces.

The folder list in this article doesn't match my install, some are missing.

Two reasons. First, version: a fresh PrestaShop 8/9 may keep DB credentials in app/config/parameters.php rather than config/settings.inc.php, and the Symfony layout under /src/ and /app/ shifts between versions. Second, security hardening: many production stores rename the admin folder, delete /install/ after setup, and restrict access to /config/ and /app/config/. A missing /install/ directory is a good sign, not a broken install.

How do I find which file handles a specific page or feature?

Start from the URL. A front-office page maps to a controller in controllers/front/ (or a module's controllers/front/); the matching template is in your active theme under templates/. For admin pages, check whether the screen is legacy (controllers/admin/) or Symfony (src/PrestaShopBundle/Controller/). Newer screens are Symfony. Enable _PS_MODE_DEV_ and the debug toolbar to see exactly which controller and template rendered a given page; that is far faster than guessing from filenames.

This Is Part 1 of a Series

This overview gives you the map. The following articles in this series will take you inside each directory with the depth that a reference guide demands -- file by file, pattern by pattern, with real examples from production stores.

The PrestaShop Architecture Series:

• Folder Structure Overview (this article) -- what every directory does at a glance
• /themes/ Deep Dive -- template resolution, asset pipeline, child theme internals, Hummingbird vs Classic, CSS layers, how Smarty renders a page from request to HTML
• /modules/ Deep Dive -- module lifecycle, hook registration, upgrade scripts, the install/uninstall chain, how config.xml caching works, autoloading patterns
• /classes/ and /src/ Deep Dive -- ObjectModel internals, how legacy and Symfony coexist, the Adapter layer, CQRS command/query patterns in PS 8/9
• /controllers/ Deep Dive -- front vs admin controllers, Symfony migration status per page, routing, how hooks are called per controller
• /config/ and /var/ Deep Dive -- configuration loading sequence, cache layers (Smarty, Symfony, OPcache, Redis), debug flags, the defines.inc.php reference
• /override/ Deep Dive -- how the override system works internally, class_index.php, why it conflicts, what replaces it in PS 9, when to use it vs hooks
• /img/ Deep Dive -- image storage by ID digits, regeneration pipeline, WebP generation, CDN integration, the image type system

Each article is written from the perspective of someone who has built and maintained 150+ PrestaShop modules across PS 1.6, 1.7, 8, and 9. This is not documentation rewritten from the official docs -- it is practical knowledge from years of debugging, profiling, and building production systems.