---
id: configuration
title: Configuration
---

import { Callout } from "nextra/components";
import { FileTree } from "nextra/components";

# Configuration

Configure FVM and IDEs for better support for different development environments.

## Project

There are two main parts for a project that has FVM configured: the `.fvmrc` config file and the `.fvm` directory.

### Config File `.fvmrc`

This contains the version linked to the project. This file is automatically created when you run `fvm use {version}`. Here you can also find project-specific settings and flavors.

```json
{
  "flutter": "3.19.0",
  "flavors": {
    "development": "beta",
    "production": "3.19.0"
  },
  "updateVscodeSettings": true,
  "updateGitIgnore": true,
  "runPubGetOnSdkChanges": true
}
```

-  `flutter`: The version of the Flutter SDK to be used, falling back to the flutter value if not explicitly set.
-  `cachePath`: Defines the path to the project's cache directory.
-  `useGitCache`: (default: true) Indicates whether the Git cache is used for dependencies.
-  `gitCachePath`: Sets the path to the Git cache directory, applicable if useGitCache is true.
-  `flutterUrl`: Specifies the URL to the Flutter SDK repository.
-  `privilegedAccess`: (default: true) Determines if configurations requiring elevated permissions are enabled.
-  `flavors`: A map defining custom project flavors for different configurations.
-  `updateVscodeSettings`: (default: true) Flags whether to auto-update VS Code settings on configuration changes.
-  `updateGitIgnore`: (default: true) Indicates whether to auto-update the .gitignore file based on project configurations.
-  `updateMelosSettings`: (default: true) Indicates whether to auto-update Melos configuration files.
-  `runPubGetOnSdkChanges`: (default: true) Triggers flutter pub get automatically upon Flutter SDK version changes.

### .fvm Directory

Inside the directory, you will find the following files and symlinks:

<FileTree>
  <FileTree.Folder name=".fvm" defaultOpen>
    <FileTree.File name="flutter_sdk" />
    <FileTree.File name="fvm_config.json" />
    <FileTree.File name="release" />
    <FileTree.File name="version" />
  </FileTree.Folder>
</FileTree>

-  **flutter_sdk** - Symlink to the Flutter SDK version linked to the project (points to the cached version).
-  **fvm_config.json** - (deprecated) Legacy configuration file for backward compatibility.
-  **release** - (internal use only) File containing the release version of FVM.
-  **version** - (internal use only) File containing the version of FVM that created this configuration.

<Callout type="tip">
  Need IDE-specific steps? Follow the [Android Studio and IntelliJ workflow guide](/documentation/guides/workflows#android-studio--intellij) to point the IDE at the project's `.fvm/flutter_sdk` symlink and refresh caches after switching versions.
</Callout>

<Callout type="warning">
  If `.fvm/flutter_sdk` is missing, run `fvm use <version>` in the project root to recreate the symlink before reopening the IDE.
</Callout>

<Callout type="info">
  Starting with version 3.0 and above, it is recommended to add the `.fvm` directory
  to your `.gitignore` file. FVM will automatically add it to .gitignore when
  pinning a version to a project if `updateGitIgnore` is set to `true`.
</Callout>

## Environment Variables

Set environment variables at the system level to apply configurations globally. These are typically used for settings that remain constant across multiple projects or runtime environments.

## Supported Environment Variables:

-  `FVM_CACHE_PATH`: Specifies the cache path for Flutter versions.
-  `FVM_USE_GIT_CACHE`: Enables/disables the git cache globally (`true`/`false`).
-  `FVM_GIT_CACHE_PATH`: Sets the path for the local git reference cache.
-  `FVM_FLUTTER_URL`: Defines the Flutter repository git URL.

### Legacy and Deprecated Variables:

-  `FVM_HOME`: ⚠️ **Legacy** - Use `FVM_CACHE_PATH` instead. Still supported as fallback for backward compatibility.
-  `FVM_GIT_CACHE`: ❌ **Deprecated** - Use `FVM_FLUTTER_URL` instead. No longer supported.
