# How to Update Tools with the aqua update Command: A Complete Guide > Learn to update tools with the aqua update command in aquaproj. Refresh tool versions in aqua.yaml, select specific packages, or use interactive updates. - Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua) - Tags: how-to-guide - Published: 2026-02-25 --- **Use `aqua update` to automatically refresh the versions of tools declared in your aqua.yaml file, with options to target specific packages, use interactive selection, or limit updates to registries only.** The `aqua update` command is the primary mechanism for keeping your development tools current in the aquaproj/aqua ecosystem. Whether you are managing a single project or an organization-wide toolchain, understanding how to update tools with the aqua update command ensures your dependencies remain secure and feature-rich without manual version hunting. ## How aqua update Works The update process operates through three distinct phases defined in [`pkg/controller/update/update.go`](https://github.com/aquaproj/aqua/blob/main/pkg/controller/update/update.go). ### Configuration Discovery The controller first locates your configuration file using the **config-finder** component. It searches for [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) starting from the current working directory, or uses the path specified with the `-c` flag. If no configuration file is found, the process returns `finder.ErrConfigFileNotFound` and exits【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L24-L30】. ### Reading Configuration and Checksum Data Once located, the configuration file is unmarshaled into the `aqua.Config` struct defined in [`pkg/config/aqua/config.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/aqua/config.go). If checksum verification is enabled (`param.ChecksumEnabled`), the controller opens the **[`aqua-checksums.json`](https://github.com/aquaproj/aqua/blob/main/aqua-checksums.json)** file using the **checksum** package to validate existing installations【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L82-L88】. ### Registry and Package Updates The actual update occurs in two sequential steps: 1. **Registry Installation**: Unless the `--only-package` flag is set, the controller calls `registryInstaller.InstallRegistries` to ensure the latest registry definitions are present before querying package versions【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L92-L99】. 2. **Package Refresh**: The `c.updatePackages` method queries remote sources (GitHub Releases, Git tags, crates.io) for the latest versions and writes the updated version strings back into [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml)【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L92-L99】. ## Command-Line Flags and Options The `aqua update` command respects a rich set of flags that shape the update workflow: - **`-r`, `--only-registry`**: Skip package updates and refresh only the registries. - **`-p`, `--only-package`**: Skip registry updates and refresh only the packages. - **`-i`**: Launch a fuzzy-finder UI to interactively select which packages to upgrade. - **`-s`, `--select-version`**: After picking packages with `-i`, also pick the target version (defaults to showing the latest 30). - **`-l `**: Change the number of versions shown by the picker (`-1` = unlimited). - **`-t ` / `--exclude-tags `**: Filter packages by user-defined tags. - **`-c `**: Explicitly point to a configuration file other than the nearest [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml). > **Important**: `aqua update` only rewrites **version** fields in the configuration. It does not modify commit hashes. If a package has a pinned `version:` entry, it remains untouched according to the source code documentation【/cache/repos/github.com/aquaproj/aqua/main/website/docs/reference/usage.md#L81-L88】. ## Practical Usage Examples Here are concrete commands for common update scenarios: ```bash # Update all registries and packages to the latest versions aqua update # Update only the registries (skip packages) aqua update -r # Update only the packages (keep current registries) aqua update -p # Interactive selection of packages to upgrade aqua update -i # Interactive selection of packages AND target versions aqua update -i -s # Show all available versions for the interactive picker aqua update -i -s -l -1 # Update a specific tool by its command name aqua update gh # Upgrade a tool to a specific version aqua update gh@v2.30.0 # Use a custom configuration file aqua -c path/to/custom/aqua.yaml update ``` ## Internal Implementation Details When you specify a package name or command name (e.g., `aqua update gh`), the controller resolves the command to a package using the **`which`** component【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L45-L50】. If you provide an explicit version constraint like `gh@v2.30.0`, that version is recorded directly. Otherwise, `c.getPackageNewVersion` queries the upstream source (GitHub Releases, tags, or crates.io) for the latest release and returns the version string. The controller then writes this back to the configuration file using `c.updateFile`【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L55-L62】. ## Summary - **`aqua update`** automates version management by scanning [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml), querying remote sources, and writing back the latest versions. - The command operates in three phases: configuration discovery, checksum validation, and registry/package updates. - Use flags like `-r`, `-p`, `-i`, and `-s` to control whether you update registries, packages, or use interactive selection. - The implementation in [`pkg/controller/update/update.go`](https://github.com/aquaproj/aqua/blob/main/pkg/controller/update/update.go) handles command resolution via the `which` component and version querying through `getPackageNewVersion`. ## Frequently Asked Questions ### Does aqua update modify commit hashes or only version strings? `aqua update` only modifies the **version** fields in your [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) configuration. It does not rewrite commit hashes. If a package entry already has a pinned `version:` field, the command leaves it untouched to prevent accidental overrides of explicit version constraints. ### Can I update a specific tool without affecting others? Yes. You can pass the command name or package name as an argument to update a single tool. For example, `aqua update gh` updates only the package providing the `gh` command. You can also use the `-i` flag to launch an interactive fuzzy-finder and select specific packages from a list. ### What is the difference between updating registries and updating packages? Registries contain the metadata and installation logic for tools, while packages are the actual tool versions you use. The `-r` (`--only-registry`) flag updates only the registry definitions, ensuring you have the latest package schemas. The `-p` (`--only-package`) flag skips registry updates and only refreshes the tool versions in your configuration. By default, `aqua update` performs both operations sequentially. ### How does aqua update handle configuration files in subdirectories? The command uses the **config-finder** component to locate the nearest [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) starting from the current working directory and walking up the directory tree. If you need to target a specific configuration file outside this search path, use the `-c` flag followed by the absolute or relative path to the file.