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

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, 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. 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 – 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 – Contains the Windows implementation using the xdg library with the same fallback path structure.
• 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:

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:

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 (Unix) and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}