--- source: https://carbone.io/documentation/developer/on-premise-installation/upgrade-guide.html title: "Upgrade Guide" description: "How to upgrade between versions" generated_at: "2026-07-13" --- # Upgrade Guide How to upgrade between versions ## How to Upgrade Upgrading Carbone is usually a simple process, as most steps are managed automatically. - First, review our comprehensive [Breaking Changes](#breaking-changes) guide. - Then, if needed, follow the step-by-step instructions that match your Carbone deployment method: | Your Environment | Upgrade Steps | | --- | --- | | Cloud | [Change the API version](/documentation/developer/http-api/introduction.md#api-version) | | On-Premise binary | Install the new binary as you would during a standard installation. Carbone keeps your existing directories (templates, config, database, ...). | | On-Premise with Docker | Ensure your templates and (optional) database are stored on persistent storage. Then pull the new image. | ## Breaking Changes We strive to [avoid introducing breaking changes](/documentation/design/overview/philosophy.md#our-vision) to your templates. However, certain breaking changes may occur in [plugins](/documentation/developer/on-premise-installation/plugins.md) or the [Studio Web Component](/documentation/design/overview/version-lifecycle.md). The table below provides a quick overview of what to check when upgrading Carbone. | Version | Breaking changes | | --- | --- | | `v3.x.x` | No. | | `v4.x.x` | No. See notes 1 and 2 below. | | `v5.0.x` | No. See notes 1 and 2 below. Also review the new [template ID concept](/documentation/developer/http-api/introduction.md#template-id). | | `v5.1.0` | Avoid this version if you use the Studio Web Component | | `v5.1.1` | [Breaking changes](#v5-0-v5-1-1) in the Studio Web Component **only**. | > ℹ️ **Note:** Note 1. Carbone now detects more syntax errors than before. Some templates that previously worked with unusual or undocumented syntax may now produce errors that need to be fixed. > ℹ️ **Note:** Note 2. The Docker images (On-Premise) and Cloud Edition now use the latest converters (LibreOffice, OnlyOffice, Chrome) available at the time of the Carbone release, which generally improves DOCX/ODT to PDF conversion. However, we recommend verifying that your documents are converted correctly. In our experience, conversions work reliably when documents are properly designed and do not use unusual formatting or design workarounds. For reference, the Cloud API v5 uses LibreOffice 25.2 while Cloud v4 uses LibreOffice 7.5, so DOCX to PDF output can differ when moving from v4 to v5. Please find more information about our [Release Lifecycle here](/documentation/design/overview/version-lifecycle.md). ## v5.0 -> v5.1.1 Applies only if you use the [Embedded Studio Web Component](/documentation/developer/embedding/studio-web-component.md). ### Studio Web Component **New embedded modes** Please carefully review the [two execution modes](/documentation/developer/embedding/studio-web-component.md#embedded-mode) of the Studio Web Component. By default, the studio starts in "embedded" mode, as in version 5.0. However, note that in 5.1.1, the "Save" button has been removed from this mode. **Function changes** The function `openTemplate(templateObj, options)` is now deprecated and has been replaced in version 5.1.1. Suppose you have these initial constants: ```js const _previewOptions = { data : {} } const _templateObject = { templateId : '212121212121212', extension : 'docx', comment : 'file name' } ``` If your code currently uses: ```js studio.openTemplate(_templateObject, _previewOptions); ``` Update it as follows for Carbone Studio 5.1.1 and above: ```js // First, set the preview options: studio.setRenderOptions(_previewOptions, false); // Then, open the template by its version ID and type: studio.openTemplateVersionId(_templateObject.templateId, _templateObject.extension, _templateObject); ``` Or use one of the [5 new ways](/documentation/developer/embedding/studio-web-component.md#open-a-template) to open a template. This ensures forward compatibility and uses the new recommended API. **Event changes** ```js // The event is triggered for additional user interactions (such as language, timezone, converter, currency). // These extra attributes are now included in the 'options:updated' event in 5.1.x and above. studio.addEventListener('options:updated', (e) => { console.log('options:updated', e.detail); // { // data : Object|Array, // complement : Object|Array, // enum : Object, // translations : Object, // // ADDITIONAL ATTRIBUTES IN 5.1: // lang : String, // timezone : String, // converter : String, // currencySource : String, // } }); // Carbone now always returns a valid data-URI and createdAt. // In Carbone 5.0, it sometimes returned a plain base64 string (without the data-URI prefix). studio.addEventListener('template:updated', (e) => { console.log('template:updated', e.detail); // AFTER 5.1.x // { // createdAt : 1767108187, // type : "html", // dataURI : "data:text/html;base64,PCFET0NUWVBFIGh0bWw+PGh0bWw+PGJvZHk+PGRpdj5hemRhemQ8L2Rpdj48L2JvZHk+PC9odG1sPg==" // } // BEFORE 5.0.x // { // type : "html", // dataURI : "PCFET0NUWVBFIGh0bWw+PGh0bWw+PGJvZHk+PGRpdj5hemRhemQ8L2Rpdj48L2JvZHk+PC9odG1sPg==" // } }); // Since Carbone v5.1, a reference to the complete internal template object is returned (with the same attributes as the Template HTTP API). // This object should be cloned before any modification, as it is a direct reference. // Internal fields starting with "_" may exist and could be hidden or renamed in future versions. studio.addEventListener('template:saved', (e) => { console.log('template:saved', e.detail); // AFTER 5.1.x // { // versionId : "a53593973e6ec37c2b79fb9128cc602c830afbb44de4bd0db719b0b71e34fc77", // id : "1317319105326582256", // createdAt : 1767109431, // expireAt : 0, // deployedAt : -1, // size : 66, // type : "html", // name : "My Template", // comment : "", // tags : [], // origin : 1, // sample : [ // { // "data": {}, // "complement": {}, // "enum": {}, // "translations": {} // } // ], // } // BEFORE 5.0.x // { // "templateId": "424242424242424242424242424", // "extension": "docx" // } }); ``` ## Related topics - [Template management](/documentation/developer/on-premise-installation/template-management.md) - [On-Premise Requirements](/documentation/developer/on-premise-installation/requirements.md) - [On-Premise plugins](/documentation/developer/on-premise-installation/plugins.md) - [Metrics (OpenMetrics)](/documentation/developer/on-premise-installation/metrics.md) - [On-Premise](/documentation/developer/on-premise-installation/introduction.md) - [Deploy on MacOS](/documentation/developer/on-premise-installation/install-on-macos.md)