Dolibarr is one of the most popular open-source ERP and CRM systems available for small to medium-sized enterprises. One of the biggest reasons for its widespread adoption is its modular structure, which allows users to extend its capabilities significantly by installing and activating modules. These modules can add everything from new functionalities, integrations with third-party platforms, to specific industry features tailored to your business needs.

However, for those new to Dolibarr or to open-source ERP systems in general, installing a module—especially one not included by default—can seem confusing at first. This guide aims to provide a detailed, beginner-to-advanced level walkthrough on how to install a module in Dolibarr, whether it's from the Dolistore, a third-party source, or a custom development.

We’ll cover:

• Understanding modules in Dolibarr

• Finding and selecting the right module

• Downloading and preparing the module files

• Manual vs automatic installation

• Permissions and prerequisites

• Troubleshooting common issues

• Post-installation configurations and good practices

Let’s begin.

1. Understanding Modules in Dolibarr

Dolibarr is built around a modular core. Every functional component in Dolibarr—be it invoicing, CRM, stock management, or even calendar—is implemented as a module. This means that new capabilities can be added just by enabling or installing modules.

There are three main types of modules:

• Core Modules: Included with Dolibarr by default; these can be activated via the admin interface.

• Official External Modules: Developed by the Dolibarr team or verified contributors and usually available on Dolistore.

• Third-Party or Custom Modules: Developed by the community or private developers, not officially verified.

Each module typically includes a directory with PHP files, configuration scripts, and possibly SQL files to create or modify database tables. When you install a module, Dolibarr detects and registers it via specific entry points.

2. Finding the Right Module for Your Needs

Before installation, you must identify the module that best fits your requirements.

Start by defining your objective:

• Do you need to integrate Dolibarr with a specific platform (e.g., PayPal, Stripe, Shopify)?

• Are you looking to improve a workflow, like HR management, document automation, or project tracking?

• Do you need compliance-related tools for tax, invoicing, or sector-specific reporting?

Where to search:

• Dolistore: The official marketplace. You’ll find both free and paid modules here, with reviews and version compatibility.

• GitHub: Many open-source developers publish modules here. Always read the README carefully.

• Dolibarr Forums & Community: Useful for discovering community recommendations and niche plugins.

• Freelance Developers: If your business has very specific needs, consider a custom module.

Always check:

• Compatibility with your Dolibarr version

• Date of last update

• Installation and usage documentation

• Whether the module has dependencies

3. Preparing to Install: Prerequisites

Before installing, take the following steps to prepare your environment:

• Back up your instance: Always backup both files and database.

• Check PHP and MySQL versions: Ensure they are compatible with your Dolibarr version.

• Ensure file upload access: You’ll need FTP or SSH access if installing manually.

• Check for conflicts: Avoid duplicate modules or functions.

A typical Dolibarr module will be a ZIP or TAR file containing one or more directories, including a main directory named after the module.

4. Manual Installation of Modules

This is the most common method for third-party or custom modules.

Step-by-step guide:

Step 1: Extract the Module

• Unzip the module package on your local machine. You should see a folder like mynewmodule/.

Step 2: Upload to Dolibarr

• Use an FTP client (like FileZilla) or SSH access to connect to your Dolibarr server.

• Navigate to the /htdocs/custom/ directory (this is where custom modules go).

• Upload the entire mynewmodule/ folder here.

Important: Do not upload to /htdocs/core/modules/ unless specifically instructed by the module developer.

Step 3: Set Permissions Ensure your web server can read the files:

chown -R www-data:www-data /path/to/dolibarr/htdocs/custom/mynewmodule
chmod -R 755 /path/to/dolibarr/htdocs/custom/mynewmodule

Step 4: Activate the Module

• Log in to Dolibarr as an administrator

• Navigate to Home > Setup > Modules/Applications

• Scroll through the list or use the search bar to find the module

• Click “Enable” or “Activate”

If the module includes a setup wizard, follow it to configure options.

5. Installation from Dolistore (Web Interface)

Some modules support direct installation via Dolibarr's built-in Dolistore integration.

Step-by-step guide:

• Navigate to Home > Setup > Modules > Dolistore

• Browse or search for the desired module

• Click install (you may need to log in with a Dolistore account)

• Dolibarr downloads and places the module automatically into /custom/

• Activate it like any other module

Note: Not all modules on Dolistore support this feature. Some still require manual upload.

6. Post-Installation Steps

Once installed and activated, configure the module:

• Go to Home > Modules and find the module in the list.

• Click on the module to open its settings page.

• Define permissions: go to Users & Groups > Permissions and assign roles accordingly.

• Set default parameters and integrations if available (e.g., API keys, file paths).

Additional Tips:

• Always read the README or documentation provided with the module.

• Some modules require database updates: Dolibarr usually handles these when enabling the module.

• Clear cache if something doesn’t show up as expected.

7. Updating Modules

Module developers release updates to add features, improve performance, or fix bugs.

To update a module:

• Download the latest version from Dolistore or the developer’s site.

• Delete the old module folder from /custom/

• Upload the new version

• Reassign permissions if necessary

• Test to ensure nothing broke

Always back up your system before performing updates.

8. Troubleshooting Common Module Installation Issues

Problem: Module not appearing in the list

• Check that it is in /htdocs/custom/ and not elsewhere.

• Ensure it has a valid modMyModule.class.php main class file.

Problem: White screen or error after activation

• Check the logs in /dolibarr/documents/admin/system/ or web server logs

• Verify PHP version compatibility

Problem: Conflicting features

• Disable similar modules that may conflict

• Avoid using duplicate modules with the same namespace

Problem: Missing permissions or features not working

• Go to Users > Permissions and explicitly assign the new permissions

9. Removing or Uninstalling a Module

If you no longer need a module:

• Disable it from the Modules section

• Delete the module folder from /htdocs/custom/

• Be cautious: some modules write data to the database that remains unless explicitly removed

Some modules provide uninstall scripts—consult their documentation.

10. Best Practices for Module Management

• Version Compatibility: Only install modules tested for your Dolibarr version.

• Source Verification: Only use trusted modules; poorly written modules can be security risks.

• Documentation: Maintain a changelog of installed modules.

• Testing: Test in a staging environment before deploying to production.

• Backup: Regularly back up files and databases, especially before installing or updating modules.

• Community Participation: Report bugs and contribute improvements back to module authors.

Conclusion

Modules are the backbone of Dolibarr’s extensibility. Whether you're looking to add eCommerce integration, automate workflows, or implement advanced analytics, installing the right module can dramatically boost productivity and adapt Dolibarr to your exact needs.

By following the steps outlined in this guide—identifying the right module, installing it properly, configuring permissions, and following up with maintenance—you can make the most of what Dolibarr has to offer while minimizing risks and frustrations. Always stay informed, document your changes, and engage with the vibrant Dolibarr community to continuously improve your ERP experience.