You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to manage FlutterFlow version for your project.
6
+
description: Learn how to manage the FlutterFlow version used for your project.
7
7
sidebar_position: 7
8
8
---
9
9
10
-
# FlutterFlow Version Management
10
+
# Pinning Projects to Stable FlutterFlow Versions
11
11
12
-
FlutterFlow is constantly evolving to provide new features, address bugs, and keep up-to-date with Flutter and third-party packages. However, frequent updates can sometimes introduce unwanted changes or conflicts that break existing projects—especially those that rely on custom code or specific Flutter/package versions.
12
+
FlutterFlow is constantly evolving to provide new features, address bugs, and keep up-to-date with Flutter and third-party packages. However, frequent updates can introduce unwanted changes that break existing projects—especially those that rely on custom code with external dependencies.
13
13
14
-
To mitigate these issues, FlutterFlow offers you a **Version Management** system that allows you to pin your project to a particular stable release of FlutterFlow. Projects pinned to a stable release will **not** automatically receive the latest FlutterFlow updates, giving you more control and stability over your development environment.
14
+
To mitigate these issues, FlutterFlow offers a **version management** system that allows you to pin your project to a particular [*stable release*](#stable-release-corresponds-to-minor-version) of FlutterFlow. Projects pinned to a stable release will **not automatically receive the latest FlutterFlow updates**, giving you more control over your development workflow.
15
+
16
+
However, pinning to a stable release means that you will not be able to use the latest features and there may be bugs that are not fixed until subsequent releases.
15
17
16
18
:::info
17
19
Currently, the ability to pin a FlutterFlow project to a stable version is only available to **Enterprise** users.
18
20
:::
19
21
20
-
## Why Version Management Matters
22
+
## When should you pin your project to a stable version?
23
+
24
+
Pinning your project to a stable version of FlutterFlow offers the following benefits:
21
25
22
-
-**Prevents Unexpected Breakage:** Frequent updates to FlutterFlow can break your project—particularly custom code—if underlying Flutter or package versions change. Pinning to a stable release ensures that your project’s code will not be affected by unexpected FlutterFlow updates.
23
-
-**Offers Control Over Update Timing:** FlutterFlow updates might occur at inopportune times (e.g., right before you plan to deploy). Version Management allows you to choose **if and when** to move your project to a newer release.
24
-
-**Enhances Reliability:** By using the pinned version, you can be confident that the same version of FlutterFlow, Flutter, and packages that you’ve tested will remain consistent, preventing surprises during critical development or deployment stages.
26
+
-**Prevents Unexpected Breakages:** FlutterFlow updates can introduce errors into your project—particularly when you have custom code. Pinning to a stable release reduces the risk of unexpected changes to your project.
27
+
-**Gives Control Over Update Timing:** FlutterFlow updates might occur at inopportune times (e.g. right before you plan to release a new version of your application). Pinning your project to a stable version allows you to choose **when** to move your project to a newer release.
25
28
26
29
:::warning
27
-
That said, there are **downsides** to consider: pinning your project to a stable release means you won’t receive the newest FlutterFlow features or bug fixes as they’re released. **We only recommend doing this if you have complex app with dependencies or custom code that could break when upgraded.**
30
+
That said, there are **downsides** to consider: pinning your project to a stable release means you won’t receive the newest FlutterFlow features or bug fixes as they’re released. **We only recommend pinning to a specific version if you have a complex app with custom code dependencies.**
28
31
:::
29
32
30
33
## Key Concepts
31
34
32
-
Below are the foundational ideas behind FlutterFlow’s Version Management system. Understanding these concepts will help you maintain project stability and control when upgrading.
35
+
To understand FlutterFlow's version management system, it's import to understand **Semantic Versioning**.
33
36
34
-
### Stable Release
37
+
FlutterFlow tends to release a new version of the product each week. When a new version is released, the overall version number is incremented.
35
38
36
-
A **stable release** of FlutterFlow is a version that has passed careful testing and is frozen to a specific:
39
+
The version number consists of three parts:
37
40
38
-
- FlutterFlow frontend
39
-
- Project code generation
40
-
- Flutter version
41
-
- Set of Pubspec dependencies
41
+
-**Major Version:** Incremented when introducing substantial changes that significantly alter the product.
42
+
-**Minor Version:** Incremented for changes that notably enhance or modify the FlutterFlow development experience—such as upgrading to a new Flutter version or adding a large feature.
43
+
-**Patch Version:** Incremented with routine releases that include new features, improvements, or bug fixes.
Stable releases are chosen on a regular cadence (e.g., quarterly or monthly). **Note** that each stable release will be supported for a set duration (6 months by default).
47
+
You can see what version of FlutterFlow you are using by looking at the top left hand corner of the builder.
When you “pin” your project to a stable release, no updates from FlutterFlow will apply to your project during the pinned period. Each stable release will have associated web and desktop frontends, allowing you to continue working on your project without interruptions.
49
51
50
-
:::info
51
-
-**For Desktop**: You will [**download**](https://www.flutterflow.io/desktop) and install the dedicated binary for the pinned stable release. This binary won’t auto-update to give you a consistent development environment.
52
-
-**For Web**: You will be automatically redirected to the unique URL when you open a project from the dashboard.
53
-
-**No forced upgrades**: You won’t be prompted to switch to the latest FlutterFlow release until your pinned version’s support window (e.g., 6 months) has ended.
54
-
-**Pinning only from main branch**: You can only pin a FlutterFlow version if your project is on the main branch; pinning from other branches isn’t allowed.
55
-
:::
52
+
#### Standard Release [Corresponds to Patch Version]
56
53
57
-
### Viewing and Modifying Pinned Versions
54
+
A **Standard Release** of FlutterFlow is released approximately every week. However, this is subject to change based on user needs.
58
55
59
-
You can check the project’s pinned FlutterFlow version from the Dashboard.
56
+
When your project is **not pinned** to a stable release (default behavior), you will automatically use the **latest standard release.**
#### Stable Release [Corresponds to Minor Version]
62
59
63
-
To change the pinned version, navigate to **Settings and Integrations > General > App Details >** scroll down to the **Version Pinning** section and select the stable release you want to lock into. Once you update the pinned version, you can only edit the project using that version of FlutterFlow.
A **Stable Release** of FlutterFlow is released each time a new **Minor Version** of FlutterFlow is created. This happens when:
63
+
64
+
- New features have undergone more testing
65
+
- There has been significant changes to project code generation
66
+
- There has been an update to the underlying Flutter or Pubspec dependency versions
67
+
68
+
Stable releases are usually deployed each month. A stable release will correspond with an underlying standard release (i.e. 1.0 corresponds to 1.0.1 in the above diagram).
69
+
70
+
:::note
71
+
Each stable release will be supported for **6 months** before you are forced to upgrade to the next stable version.
72
+
:::
73
+
74
+
75
+
## Pinning Your Project
66
76
67
-
You can upgrade to a newer release or switch to an older one. However, if you choose to downgrade, any changes made after moving to a higher version will be lost.
77
+
To pin your project, navigate to **Settings and Integrations > General > App Details >Version Pinning** section and select the stable release you want to lock into. Once you update the pin your project to a stable version, you can only edit the project using that version of FlutterFlow.
78
+
79
+
68
80
69
81
:::info
70
-
**Note that**only project owners can modify the pinned version.
82
+
You can only pin a project to a stable version if you are the **Project Owner**and you are on the **main** branch.
71
83
:::
72
84
85
+
### Modifying the Pinned Version
86
+
87
+
You have several options when it comes to modifying pinned version of your project:
88
+
89
+
-**Upgrade to more recent Stable Version**: When a new stable version is released, you will see it as an option in the dropdown shown above. You can upgrade the pinned version to a more recent stable version whenever they become available. Newer stable versions will have higher numbers (i.e. 5.1 is newer than 5.0)
90
+
-**Downgrade to a previous Stable Version:** You can downgrade to a prior stable release (i.e. downgrade from 5.1 to 5.0), however **changes made since upgrading will be lost** (i.e. changes made after modifying pinned version from 5.0 to 5.1). Therefore, we recommend [commiting](https://docs.flutterflow.io/collaboration/branching/#create-commits) all changes on the main branch before upgrading - plus testing after upgrading so you can quickly downgrade if necessary.
91
+
-**Set to *Latest Version* (Unpinned):** You can unpin your project by setting it to the *Latest Version* which will use the latest [standard release](#standard-release-corresponds-to-patch-version).
92
+
-**Opt-in to the *Next Stable*:** Your project may be on a standard version that does not have a correspond stable version (i.e. you are on 5.0.1 but the 5.0 stable will correspond to 5.0.4). In that case, you can choose to opt-in to the *Next Stable Version*. This will pin your project to the next stable version once it becomes available.
93
+
94
+
### Accessing the Proper Stable Version
95
+
As mentioned above, once you update the pin your project to a stable version, you can only edit the project using that version of FlutterFlow.
96
+
97
+
-**For Web**: You will be automatically redirected to the URL for the stable version that your project is pinned to when you open a project from the FlutterFlow dashboard (i.e. navigating to app.flutterflow.io or enterprise-[region].flutterflow.io).
98
+
-**For Desktop**: You will [**install**](https://www.flutterflow.io/desktop) the dedicated desktop application for the pinned stable release. The desktop app for stable releases won’t auto-update, you will need to install a new version when you upgrade your project to a new stable version.
99
+
73
100
74
101
## Recommended FlutterFlow Version Workflow
75
102
76
103
If you have a complex app with custom code that depends on specific versions of package dependencies, it may be helpful to pin your project to a specific version. This is the workflow we recommend for managing the version of your projects.
77
104
78
-
1.You’ll be notified when a new stable version is released, typically every four weeks.
105
+
1.If you think your project should be pinned to a stable release, choose to [pin the project to the current (if available) or next stable release](#modifying-the-pinned-version).
79
106
2. When a new stable version is released, you can choose when you would like to upgrade based on your own release schedule and development process. For instance, you might wait until you're not actively developing a new feature, or you could check the release notes first to see if there are must-have features that would prompt you to upgrade sooner.
80
-
3. When you’re ready to upgrade, update the pinned version and create a new branch in your project. Run your app on the platforms you support—using a simulator, emulator, or physical device to ensure everything works as intended.
81
-
4. If everything looks good, you're good to go! If for some reason your app is not working as expected, you can choose to revert the version and lose those testing changes until you are ready to make the modifications needed to support the latest FlutterFlow version (i.e., upgrade dependencies/custom code).
107
+
3. When you’re ready to upgrade, commit all your changes on main to save your progress and [update the pinned version](#modifying-the-pinned-version).
108
+
4. Run your app on the platforms you support—using a simulator, emulator, or physical device to ensure everything works as intended. See the [Local Run documentation](https://docs.flutterflow.io/testing/local-run/) for details.
109
+
4. If everything looks good, you're good to go! If for some reason your app is not working as expected, you can choose to revert the version and lose those testing changes until you are ready to make the modifications needed to support the latest FlutterFlow version (i.e. upgrade dependencies/custom code).
82
110
83
111
:::tip
84
112
See the video [**here**](https://youtu.be/8Y1uyCC_dXE) for guidance on updating [**dependencies**](../../ff-concepts/adding-customization/custom-code.md#manage-dependencies).
@@ -91,7 +119,7 @@ See the video [**here**](https://youtu.be/8Y1uyCC_dXE) for guidance on updating
91
119
Library projects can also be pinned to a specific version, ensuring that all library versions use that FlutterFlow release until the pinned version is changed.
92
120
93
121
:::info
94
-
When you import a library into a project or another library, the library’s version must be lower than the project or library it’s being imported into; otherwise, you will encounter an error.
122
+
When you import a library into a project or another library, the library’s version must be lower than the version used for the project it’s being imported into; otherwise, you will encounter an error.
95
123
:::
96
124
97
125
## FAQs
@@ -101,8 +129,8 @@ When you import a library into a project or another library, the library’s ver
101
129
What happens if I downgrade to a lower version of FlutterFlow after making changes in a higher version?
102
130
</summary>
103
131
<p>
104
-
Any changes made in a higher version will be lost when you revert to a lower version (e.g., by pinning to the last stable release).
105
-
**To avoid data loss, thoroughly test your app after upgrading to ensure you want to continue with the updated version before downgrading.**
132
+
Any changes made in a higher version will be lost when you revert to a lower version (e.g., you made changes when you upgraded from 5.0 to 5.1, but then you want to downgrade back to 5.0).
133
+
**To avoid data loss, thoroughly test your app after upgrading to ensure you want to continue with the updated version.**
106
134
</p>
107
135
</details>
108
136
@@ -120,7 +148,7 @@ No. If your project is not pinned to a specific version, you’ll always use the
120
148
How often are new stable versions released?
121
149
</summary>
122
150
<p>
123
-
We aim to release new stable versions of FlutterFlow once a month.
151
+
We aim to release new stable versions of FlutterFlow approximately once a month.
124
152
</p>
125
153
</details>
126
154
@@ -140,4 +168,33 @@ What if there are bugs in the FlutterFlow version I’m using?
140
168
<p>
141
169
If critical bugs arise, we may provide hotfixes or patches for older FlutterFlow versions. However, some fixes depend on updating the underlying Flutter framework or related dependencies, which isn’t always feasible for older versions. This is a risk of staying on an older version of FlutterFlow as opposed to always using the latest.
142
170
</p>
171
+
</details>
172
+
173
+
174
+
<details>
175
+
<summary>
176
+
Can I change the pinned version to be different for various branches in my project?
177
+
</summary>
178
+
<p>
179
+
Right now, we only support changing the pinned version from the main branch. When a project is pinned to a stable version, the entire project (including all of the branches within that project) will need to use the stable version that was selected.
180
+
</p>
181
+
</details>
182
+
183
+
184
+
<details>
185
+
<summary>
186
+
What happens if there is no stable version available for me to pin my project to?
187
+
</summary>
188
+
<p>
189
+
If your project was created and edited on a [standard release](#standard-release-corresponds-to-patch-version) that does not correspond to a [stable version](#stable-release-corresponds-to-minor-version), you may not see an earlier stable version to downgrade to - because this would reset the state of your project. Instead, you can choose to opt-in to the [*next stable release*](#pinning-your-project).
190
+
</p>
191
+
</details>
192
+
193
+
<details>
194
+
<summary>
195
+
What is the recommended approach if I have multiple projects and libraries that I am working on?
196
+
</summary>
197
+
<p>
198
+
If you choose to pin your project to a stable version of FlutterFlow, we recommend pinning all your projects and dependencies to the same version - and trying to upgrade all projects to the next version around the same time. This makes it easier to ensure compatibilities between projects and libraries that depend on each other. Additionally, this makes it easier to have a single FlutterFlow desktop environment that you are working within.
0 commit comments