Skip to content
Odoo Migration

Odoo Migration: Handling Module Dependencies and Installation Order

A practical guide for CIOs and ERP consultants on managing Odoo module dependencies, resolving circular references, and defining the correct installation sequence during version upgrades or migrations to ensure system stability.

11 min readSysGenPro Editorial
Odoo Migration: Handling Module Dependencies and Installation Order

Direct Answer: Managing Odoo Module Dependencies and Installation Order

Handling module dependencies and installation order in Odoo migration requires a systematic analysis of the dependency graph, explicit sequencing of module installations, and rigorous testing in a staging environment. The recommended approach involves mapping all core, enterprise, and custom modules, identifying circular or missing dependencies, and defining a topological sort order for installation. This is critical because Odoo loads modules in a specific sequence to ensure data models, views, and security rules are correctly registered. Failure to manage this order can lead to database inconsistencies, broken views, or system crashes during the upgrade. The main risks to control include circular dependencies, deprecated API usage in custom modules, and version mismatches between third-party add-ons and the target Odoo version. By establishing a clear installation sequence and validating it through trial runs, organizations can protect business data and maintain operational continuity.

Understanding the Odoo Dependency Graph

Odoo modules are not independent units; they form a complex web of dependencies defined in their manifest files (odoo.conf or __manifest__.py). Each module declares its dependencies on other modules, which can be core Odoo modules, enterprise modules, or third-party add-ons. During migration, the system must resolve this graph to determine the correct installation order. A dependency graph is a directed acyclic graph (DAG) where nodes represent modules and edges represent dependencies. If the graph contains cycles (circular dependencies), the installation process will fail. Understanding this structure is the first step in planning a successful migration. The dependency graph also reveals which modules are foundational (no dependencies) and which are leaf nodes (depend on many others). Foundational modules must be installed first, while leaf nodes are installed last. This hierarchical structure ensures that all required data models and fields are available when dependent modules are loaded.

Identifying Circular Dependencies

Circular dependencies occur when Module A depends on Module B, and Module B depends on Module A, either directly or through a chain of other modules. Odoo's installation engine cannot resolve circular dependencies and will raise an error. To identify these, use Odoo's built-in tools or external dependency analysis scripts. In the Odoo interface, you can view the dependency tree for a specific module, but for a full system audit, it is better to export the dependency graph and analyze it using graph theory tools. Circular dependencies are often introduced by custom modules that incorrectly declare dependencies or by third-party add-ons that have not been updated for the target version. Resolving circular dependencies requires refactoring the code to remove the mutual dependency or splitting the module into smaller, independent components. This is a critical step in the preparation phase of the migration.

Analyzing Custom and Third-Party Modules

Custom modules and third-party add-ons are the most common sources of dependency issues during Odoo migration. Custom modules often rely on internal APIs or data structures that may change between versions. Third-party add-ons may not be compatible with the target version, leading to missing dependencies or broken functionality. To analyze these modules, review their manifest files for declared dependencies and check the vendor's documentation for compatibility with the target Odoo version. For custom modules, perform a code review to identify deprecated APIs, changed model fields, or removed views. This analysis should be documented in a migration plan, listing each module, its dependencies, its compatibility status, and any required code changes. Modules that are not compatible with the target version must be either updated, replaced, or removed before the migration can proceed.

Defining the Installation Sequence

Once the dependency graph is analyzed and circular dependencies are resolved, the next step is to define the installation sequence. This sequence is a topological sort of the dependency graph, ensuring that each module is installed only after all its dependencies are installed. Odoo's installation engine automatically calculates this order based on the manifest files, but it is essential to verify this order in a staging environment. The installation sequence should be documented and tested to ensure that it works as expected. In some cases, you may need to manually adjust the installation order by modifying the manifest files or using command-line options. For example, if two modules have no direct dependency but share a common dependency, their relative order may not matter, but if they both modify the same data model, their order may affect the final state. Testing the installation sequence in a staging environment is crucial to identify any unexpected issues.

Topological Sort and Automatic Resolution

Odoo uses a topological sort algorithm to determine the installation order of modules. This algorithm ensures that all dependencies are installed before the modules that depend on them. The algorithm is deterministic, meaning that the same set of modules will always result in the same installation order, assuming no changes to the manifest files. However, the algorithm does not account for business logic or data integrity constraints. For example, if Module A and Module B both modify the same field in the same model, the order in which they are installed may affect the final value of the field. In such cases, manual intervention may be required to ensure that the installation order aligns with business requirements. It is recommended to test the automatic installation order in a staging environment and compare the results with the expected business outcomes.

Manual Adjustments and Overrides

In some cases, the automatic installation order may not be suitable for the business needs. For example, if a custom module depends on a third-party module that is not yet available in the target version, you may need to install the custom module first and then update the third-party module. This can be achieved by modifying the manifest files to remove the dependency temporarily or by using command-line options to force the installation order. Manual adjustments should be documented and tested thoroughly to ensure that they do not introduce new issues. It is important to note that manual overrides can lead to inconsistencies if not managed carefully. Therefore, any manual adjustments should be reviewed by a senior developer and approved by the project manager before being applied to the production environment.

Preparation and Dependency Analysis

The preparation phase is critical for a successful Odoo migration. It involves a comprehensive analysis of the current system, including all installed modules, custom code, and integrations. The goal is to create a complete inventory of modules and their dependencies. This inventory should include the module name, version, source (core, enterprise, third-party, custom), and dependencies. The inventory should be used to identify any missing dependencies, circular dependencies, or incompatible modules. Additionally, the preparation phase should include a review of the database schema to identify any custom fields, views, or security rules that may be affected by the migration. This review should be documented in a migration plan, which will serve as the blueprint for the migration process.

Module TypeDependency RiskAction RequiredResponsible Role
Core OdooLowVerify version compatibilityERP Administrator
EnterpriseMediumCheck vendor support and updatesERP Consultant
Third-PartyHighVerify compatibility and update if neededSystem Integrator
CustomHighCode review and refactoringDevelopment Team

Technical Execution and Testing

The technical execution phase involves performing the migration in a staging environment that mirrors the production environment. This includes installing the target Odoo version, migrating the database, and installing all modules in the defined sequence. The staging environment should be used to test the installation order, identify any issues, and validate the business processes. Testing should include unit tests, integration tests, and end-to-end business process tests. Unit tests should verify that each module is installed correctly and that its dependencies are resolved. Integration tests should verify that the modules work together as expected. End-to-end tests should verify that the business processes are functioning correctly after the migration. Any issues identified during testing should be documented and resolved before the migration is applied to the production environment.

Staging Environment Setup

The staging environment should be a replica of the production environment, including the same hardware, software, and data. This ensures that the migration process is tested under realistic conditions. The staging environment should be used to perform trial migrations, allowing the team to identify and resolve any issues before the production migration. The trial migration should include a full backup of the production database, a restore of the backup in the staging environment, and a migration to the target version. The trial migration should be repeated multiple times to ensure that the process is reliable and reproducible. Any issues identified during the trial migration should be documented and resolved before the production migration.

Validation and Reconciliation

Validation and reconciliation are critical steps in the technical execution phase. They involve comparing the data in the staging environment with the data in the production environment to ensure that the migration has not introduced any data loss or corruption. Reconciliation should include a comparison of key business metrics, such as total sales, total inventory, and total customers. Any discrepancies should be investigated and resolved before the migration is applied to the production environment. Validation should also include a review of the security rules and access rights to ensure that they are correctly applied after the migration. This review should be performed by a security expert to ensure that the system is secure and compliant with business requirements.

Deployment and Cutover Planning

The deployment phase involves applying the migration to the production environment. This should be done during a planned downtime window to minimize the impact on business operations. The cutover plan should include a detailed runbook, specifying the steps to be performed, the responsible roles, and the go/no-go criteria. The runbook should include a backup of the production database, a restore of the backup in the production environment, and a migration to the target version. The cutover plan should also include a rollback plan, specifying the steps to be performed if the migration fails. The rollback plan should be tested in the staging environment to ensure that it is effective. The cutover plan should be reviewed and approved by the project manager and the business stakeholders before the migration is applied to the production environment.

Cutover StepDescriptionResponsible RoleEstimated Time
Backup Production DBCreate a full backup of the production databaseDBA30 minutes
Stop ServicesStop all Odoo services and integrationsIT Director10 minutes
Restore BackupRestore the backup in the production environmentDBA30 minutes
Run MigrationExecute the migration script and install modulesERP Consultant60 minutes
Validate SystemPerform smoke tests and validate key processesQA Team30 minutes
Go/No-Go DecisionReview validation results and make go/no-go decisionProject Manager15 minutes

Post-Migration Stabilization

The post-migration stabilization phase involves monitoring the system for any issues and resolving them promptly. This includes monitoring the system logs, performance metrics, and user feedback. Any issues identified during this phase should be documented and resolved as quickly as possible. The stabilization phase should also include a review of the system documentation, including the user manuals, administrator guides, and API documentation. This review should ensure that the documentation is up-to-date and reflects the changes made during the migration. The stabilization phase should continue for a defined period, typically one to two weeks, to ensure that the system is stable and reliable. After the stabilization phase, the project can be closed, and the system can be handed over to the operations team.

  • Monitor system logs for errors and warnings
  • Review performance metrics to identify bottlenecks
  • Collect user feedback and address concerns
  • Update documentation to reflect changes
  • Conduct a post-mortem review to identify lessons learned

Risk Management and Rollback Strategies

Risk management is a critical component of any Odoo migration project. The main risks include data loss, downtime, broken customizations, unsupported dependencies, integration failures, reporting discrepancies, security misconfiguration, performance regressions, user adoption, and rollback limits. To mitigate these risks, it is essential to have a well-defined rollback plan. The rollback plan should specify the steps to be performed if the migration fails, including a restore of the backup and a revert to the previous version. The rollback plan should be tested in the staging environment to ensure that it is effective. It is also important to have a communication plan in place to inform stakeholders of the migration status and any issues that arise. The communication plan should include regular updates, a point of contact, and a crisis communication protocol.

  • Data Loss: Mitigated by full backups and reconciliation
  • Downtime: Mitigated by planned downtime windows and efficient cutover
  • Broken Customizations: Mitigated by code review and testing
  • Unsupported Dependencies: Mitigated by compatibility checks and updates
  • Integration Failures: Mitigated by integration testing and monitoring
Written by
SysGenPro Editorial

SysGenPro Editorial

Platform & solutions team

Practical guidance on ERP, AI automation, cloud deployment and enterprise transformation from the SysGenPro team.

Share this article

Frequently asked questions

Common questions on this topic. Talk to our team for anything specific to your business.

01What is the correct installation order for Odoo modules?

The correct installation order is determined by a topological sort of the dependency graph, ensuring that all dependencies are installed before the modules that depend on them. This order is automatically calculated by Odoo but should be verified in a staging environment.

02How do I detect circular dependencies in Odoo?

Circular dependencies can be detected using Odoo's built-in tools or external dependency analysis scripts. They occur when Module A depends on Module B, and Module B depends on Module A, either directly or indirectly.

03Can Odoo automatically resolve module dependencies?

Yes, Odoo automatically resolves module dependencies using a topological sort algorithm. However, it does not account for business logic or data integrity constraints, so manual verification is recommended.

04What happens if a dependent module is missing during upgrade?

If a dependent module is missing, the installation process will fail, and the system may be left in an inconsistent state. It is essential to ensure that all dependencies are present and compatible before the upgrade.

05How should I test module installation order before production?

Test the module installation order in a staging environment that mirrors the production environment. Perform trial migrations, validate the business processes, and resolve any issues before applying the migration to production.

06Do custom modules need to be updated before core modules?

Custom modules should be updated to be compatible with the target version before the migration. This includes updating deprecated APIs, changed model fields, and removed views. The installation order should ensure that core modules are installed before custom modules that depend on them.

Continue learning
View all articles
Explore the platform

Where to go next

Browse the knowledge hub

See how SysGenPro fits your business

Discuss your workflows, modules and deployment options with our team.

Back to resources