# What Is the Default Installation Directory for aqua? A Complete Guide

> Discover the default installation directory for aqua on Unix and Windows systems. Learn how AQUA_ROOT_DIR overrides this location for precise control over your installations.

- Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua)
- Tags: how-to-guide
- Published: 2026-02-25

---

**The default installation directory for aqua is `$HOME/.local/share/aquaproj-aqua` on Unix-like systems and `%USERPROFILE%\.local\share\aquaproj-aqua` on Windows, unless overridden by the `AQUA_ROOT_DIR` environment variable.**

The `aquaproj/aqua` repository provides a declarative CLI version manager that installs tools into a specific directory structure. Understanding the default installation directory for aqua is essential for managing disk space, configuring CI/CD pipelines, and troubleshooting path-related issues.

## How aqua Determines the Installation Directory

aqua resolves its root directory through a prioritized lookup mechanism. The process checks environment variables in a specific order before falling back to operating system defaults.

**Priority order:**

1. **`AQUA_ROOT_DIR`** – If this environment variable is set, aqua uses it as the installation root regardless of platform.
2. **`XDG_DATA_HOME`** – On Unix-like systems, aqua checks this XDG Base Directory variable.
3. **Platform-specific defaults** – If neither variable is set, aqua falls back to hardcoded paths in the source code.

This logic is implemented in the `GetRootDir` function, which is exported from the `pkg/config` package and consumed by the CLI commands.

## Default Paths by Operating System

When `AQUA_ROOT_DIR` is unset, aqua follows XDG Base Directory Specification conventions with platform-specific implementations.

### Unix-like Systems (Linux and macOS)

On Unix platforms, the default installation directory for aqua is determined by the `XDG_DATA_HOME` environment variable. If `XDG_DATA_HOME` is empty or unset, aqua defaults to:

```

$HOME/.local/share/aquaproj-aqua

```

This path resolution is handled in [`pkg/config/root_dir.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir.go), where the implementation constructs the final path by joining the base directory with the `aquaproj-aqua` suffix.

### Windows

On Windows, aqua uses the `xdg` package to determine the appropriate data home directory. The fallback mechanism mirrors the Unix implementation:

```

%USERPROFILE%\.local\share\aquaproj-aqua

```

The Windows-specific logic resides in [`pkg/config/root_dir_windows.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir_windows.go). This file imports `github.com/adrg/xdg` to handle Windows-specific path conventions while maintaining consistency with the XDG specification.

## Locating the Installation Directory in Source Code

The default installation directory logic is split across platform-specific files to handle OS differences cleanly.

**Key source files:**

- **[`pkg/config/root_dir.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir.go)** – Contains the Unix implementation of `GetRootDir`, which checks `XDG_DATA_HOME` before falling back to `$HOME/.local/share/aquaproj-aqua`.
- **[`pkg/config/root_dir_windows.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir_windows.go)** – Contains the Windows implementation using the `xdg` library with the same fallback path structure.
- **[`pkg/cli/root/command.go`](https://github.com/aquaproj/aqua/blob/main/pkg/cli/root/command.go)** – Implements the `aqua root-dir` CLI command that prints the resolved directory path.

The `GetRootDir` function signature accepts an `osenv.OSEnv` interface, allowing for easy testing and mocking of environment variables.

## How to Check Your Current Installation Directory

You can verify the active installation directory using the built-in CLI command or by querying the configuration programmatically.

**Using the CLI:**

```bash
aqua root-dir

```

This command outputs the absolute path to the current root directory, resolving all environment variables and symlinks.

**Programmatic access (Go):**

If you are building tools that integrate with aqua, you can import the configuration package to resolve the directory:

```go
package main

import (
	"fmt"

	"github.com/aquaproj/aqua/pkg/config"
	"github.com/suzuki-shunsuke/go-osenv/osenv"
)

func main() {
	// Resolve the root directory using the current OS environment
	dir := config.GetRootDir(osenv.New())
	fmt.Println("Aqua root directory:", dir)
}

```

When executed without `AQUA_ROOT_DIR` set, this prints:

```

Aqua root directory: /home/user/.local/share/aquaproj-aqua

```

On Windows, it resolves to:

```

Aqua root directory: C:\Users\user\.local\share\aquaproj-aqua

```

## Summary

- The **default installation directory for aqua** is `$HOME/.local/share/aquaproj-aqua` on Unix systems and `%USERPROFILE%\.local\share\aquaproj-aqua` on Windows.
- aqua follows the **XDG Base Directory Specification**, checking `XDG_DATA_HOME` before falling back to the default path.
- You can override the default by setting the **`AQUA_ROOT_DIR`** environment variable.
- The resolution logic is implemented in [`pkg/config/root_dir.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir.go) (Unix) and [`pkg/config/root_dir_windows.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir_windows.go) (Windows).
- Use the **`aqua root-dir`** command to quickly check your current installation path.

## Frequently Asked Questions

### Can I change the default installation directory?

Yes. Set the `AQUA_ROOT_DIR` environment variable to any absolute path before running aqua commands. This overrides both XDG variables and platform defaults. For persistent changes, add the export to your shell configuration file (e.g., `.bashrc`, `.zshrc`, or Windows System Environment Variables).

### Does aqua follow the XDG Base Directory Specification?

Yes. On Unix-like systems, aqua checks the `XDG_DATA_HOME` environment variable first. If unset, it defaults to `$HOME/.local/share`, which aligns with the XDG specification. The Windows implementation uses the `adrg/xdg` library to provide equivalent behavior on non-Unix platforms.

### How do I find the installation directory programmatically?

Import the `github.com/aquaproj/aqua/pkg/config` package and call `config.GetRootDir(osenv.New())`. This returns the resolved path as a string, respecting all environment variables and platform-specific logic. This approach is useful for automation scripts written in Go that need to interact with aqua's installed binaries.

### What happens if AQUA_ROOT_DIR is set to an invalid path?

If `AQUA_ROOT_DIR` points to a non-existent directory, aqua will attempt to create it when installing packages. If the path is invalid (e.g., permission denied or malformed), aqua will return an error during the installation process. Always ensure the directory is writable and has sufficient disk space for the tools you plan to install.