Essential guide to installing Amazon Q Developer CLI on Linux
However you like to run Linux, Amazon Q Developer at your finger tips is only a few steps away
Ricardo Sueiras
Amazon Employee
Published Mar 24, 2025
I spend most of my time in the command line. It is my happy place. Amazon Q Developer CLI is a perfect companion for me, made even more compelling with new agentic features that were launched recently (check that post out here)
Whilst I do spend most of my time on my Mac, I wanted to dive into how I could get access to Amazon Q Developer CLI on various Linux distributions. If you spend much of your time in Linux, including headless systems, then this post is for you. I wanted to share what I had learned in doing this to help simplify life for you.
I am going to cover a few different scenarios that I typically have and use on a daily basis:
- GUI Linux systems - my daily Ubuntu machine, running desktop
- Headless Linux systems - typical Linux distributions you might use on AWS (for example, Amazon Linux 2023)
- Compiling from source - for those scenarios where you want to compile the Amazon Q Developer CLI binaries for use on other Linux systems (perfect for those package managers out there who might want to include Amazon Q Developer CLI packages in their distributions)
This should cover most scenarios, and I have found this allows me to have Amazon Q Developer everywhere I need it to be.
Before we begin the installation, lets first create our Builder ID. We will need this after we install Amazon Q Developer CLI, and we will use it to login so we can use it for free. All you need to do is register for your Builder ID using an email address, and you are good to go (there are lots of other benefits of having a Builder ID too, so make sure you check those out too).
Before proceeding with the installation of Amazon Q Developer CLI, it is worth noting some of the requirements you will need to have the "full experience". By this I mean that within the terminal you will get command line completions and suggestions. There are the documented requirements as of writing this post (check here to get updates on this)
- Platform requirements: Amazon Q for command line for Linux supports Ubuntu 22 and 24. It may otherwise work with GNOME v42+ or environments where the display server is Xorg and the input method framework is IBus.
- Terminal emulators: GnomeConsole, GnomeTerminal, Kitty, Hyper, WezTerm, Alacritty, Tilix, Terminator
- Processor Architecture: amd64
If you are running a Linux distribution locally, and have access to a GUI, then you use the existing packages that have been created for you which are documented here. If you are looking for a way to run an Ubuntu Desktop on EC2 instances, I recently showed you how you can set this up quickly with DCV in my post Configuring DCV to access Ubuntu Desktop on EC2 with a browser.
There are actually two ways you can install Amazon Q Developer CLI onto your Ubuntu desktop, so choose the one that fits your preference.
Note! There is another installation method, where Amazon Q Developer CLI is distributed via a zip package. This is intended for headless installations, and whilst it will run on a GUI installation, logging in will hang.
AppImages are becoming more popular as they package up everything in one file which you can then execute. Here is how you can get it up and running in just a few minutes:
1/ Install dependencies (this is only needed for Ubuntu)
sudo apt install libfuse22/ Grab the AppImage
curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.appimage -o amazon-q.appimage3/ Make it executable
chmod +x amazon-q.appimageYou can now run the installation program by opening the file from the GUI file manager, or running "./amazon-q.appimage" from the command line. You should see the Amazon Q Developer CLI appear. Look at this short video that shows you the process.
(source https://youtu.be/WnKWVICabnw)
You will have noticed that it did not ask me to login with my Builder ID as I had already created it before hand and had logged in.
1/ Install dependencies (this is only needed for Ubuntu)
sudo apt install libfuse22/ Download the debian package
curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o amazon-q.deb3/ Install the package
sudo apt install -y ./amazon-q.deb4/ Open up Amazon Q Developer and follow installation instructions
qWhen you type in q from the command line it will bring up the GUI tool. Follow the instructions, and after logging in with your Builder ID you should be good to go.
If you need to remove/uninstall Amazon Q Developer CLI, then its pretty straight forward. If you used the AppImage to install Amazon Q Developer, then you can run the following command:
q uninstallIf you installed via the debian package, then you can use the following command:
sudo apt purge amazon-qIn this setup we are going to install Amazon Q Developer CLI on a remote, headless Linux system.
Amazon Q Developer CLI needs glibc 2.34 or later on the host you are going to be installing it on. You can check by running this command
[ec2-user@ip-172-31-29-188 ~]$ ``ldd --versionldd (GNU libc) 2.34Copyright (C) 2021 Free Software Foundation, Inc.This is free software; see the source for copying conditions. There is NOwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.Written by Roland McGrath and Ulrich Drepper.If you have an older Linux distribution, fear not. There is a separate download file, refered to as the musl build, which should allow you to get up and running.
Before proceeding, there are two options you have. If you want the FULL functionality of Amazon Q Developer CLI (command completion as well as access to q chat and q translate), you will need to install Amazon Q Developer CLI on your local system first (don't worry I will walk you through what you need to do). If all you want is access to is q chat and q translate, you do not need to do the local stuff. You will get errors but you can ignore these.
Lets walk through what you need to do locally to get the full experience. It is very straight forward.
If you have not already installed Amazon Q Developer CLI on your local machine (either MacOS or Linux distribution - see above) then do that now. Once you have it up and running, you need to just run the following command:
q integrations install sshWhen you run it, it should simply say "Installed!". What has it done I can hear you all saying. If you look at local .ssh directory, you should see the following added to your config file
# Amazon Q SSH Integration. Keep at the bottom of this file.Match all Include "~/Library/Application Support/amazon-q/ssh"Now that we have completed our local setup, then we can now deploy Amazon Q Developer CLI on our remote, headless Linux system.
Log in to your remote Linux system. You will need to have system level privileges as we will making changes and restarting services.
1/ The first thing you are going to need to do is make an update to the sshd_config ( /etc/ssh/sshd_config) file adding the following lines to the end of the configuration:
AcceptEnv Q_SET_PARENT AllowStreamLocalForwarding yesYou should restart sshd using
sudo systemctl restart sshdDisconnect and reconnect back to the Linux host. You are now ready to deploy the Amazon Q Developer CLI binaries.
2/ The next step is optional, but recommended. We want to verify the downloaded files before we install them, so we are going to need gpg tools. These might be already installed on your system, but if not you will need to install a full version of gpg tools. How you install them will vary based on the distribution of Linux you are using. As I am using Ubuntu 2024 I used this
sudo apt-get install gnupgIf you are using different Linux distributions, check which package contains "gpg" and follow the guide to install them.
3/ Install dependencies (this is only needed for Ubuntu)
sudo apt install libfuse24/ Download the zip file
The version of the zip file you need will depend on whether your current Linux system is running older versions of glib.
If you are running a system that has glibc 2.34 or newer, then this is your download file
curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"If you have an older system, then you should download the musl builds, using this link:
wget https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zipNote! When I tried this on my Ubuntu 18.04 machine, the installation worked but I could only use q chat/q translate, with command completion not working. I am still trying to figure out how to get that going.
5/ Verify the zip file. You will need to create a local file which is the public key from the documentation here - I have created a gist here. I call this file "q-pub-key.pem" and then run this command:
gpg --import q-pub-key.pemDownload the latest version of the zip signature file
curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip.sig" -o "q.zip.sig"and then verify
gpg --verify q.zip.sig q.zipNote The warning in the output is expected and doesn't indicate a problem. It occurs because there isn't a chain of trust between your personal PGP key (if you have one) and the Amazon Q for command line PGP key. For more information, see Web of trust.
6/ Unzip the file once verified
unzip q.zip7/ Run the installation script
chmod +x q/install.sh./q/install.shAnd then follow the prompts.
? Select login method ›❯ Use for Free with Builder ID Use with Pro licenseConfirm the following code in the browserCode: PNDN-QVKBOpen this URL: https://view.awsapps.com/start/#/device?user_code=PNDN-QVKB▰▰▱▱▱▱▱ Logging in...Open up a web browser in your local machine, and use that URL. After logging in with your Builder ID and following the prompts, when it completes when you return back to the command line you should see.
Logged in successfully8/ You can now validate that Amazon Q Developer CLI is up and running by running the "q doctor".
q doctorNote! If you did not do the local stuff, you will get some errors when running q doctor - in my experience these have not stopped q chat or q translate working
The process to remove Amazon Q Developer from your Linux host is pretty straight forward:
- Delete the binaries that you copied
- (optional) Update the bash/zsh scripts to remove the .local/bin directory if you are not using it for anything else
- Remove the entries you added from the sshd configuration file (/etc/ssh/sshd_config) and restart
So far we have dealt with installing existing distributions of Amazon Q Developer CLI that have been compiled and put together by AWS. As this is an open source project, you can also compile and build your own distributions. In this section I am going to walk you through where you can look and walk you through an example of doing this. I used an Ubuntu 24.04 LTS on EC2 (t2.xlarge) for this walkthrough, connecting via a local ssh connection.
A note to Linux package managersIf you are currently involved in managing packages for a Linux distribution, then you might want to use the instructions outlined in the GitHub repo to help you build packages for your distributions. My colleague James Ward has recently done this for NixOS (you can see his PR here)
First you need to make sure you have 16GB storage free (I ran out of storage with a micro.t2.instance of 8gb).
this was a great way to use q in the console. I asked it to walk me through the process of increasing storage of an instance, and it did a brilliant job
Once you have ssh'd to your Linux host (in this case Ubuntu) we are ready to start.
1/ Lets clone the repo which we will need (don't forget to change into the directory)
git clone https://github.com/aws/amazon-q-developer-cli.gitcd amazon-q-developer-cli2/ I found the required dependencies here, so you will need to check the equivalents for your distribution. The README also provides some information which was useful to know.
sudo apt-get updatesudo apt-get install -y -qq build-essential pkg-config jq dpkg curl wget zsh zstd cmake clang libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libdbus-1-dev libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev valac libibus-1.0-dev libglib2.0-dev sqlite3 protobuf-compiler libfuse2 zipI was able to do the same thing on Amazon Linux 2023, all I had to do was switch the packages that were needed to the following:sudo dnf check-update
sudo dnf install git openssl-devel curl wget librsvg2-devel jq --allowerasing
sudo dnf make bash zsh unzip zstd xz git jq protobuf
This took around 5 mins to update and install these packages.
3/ The next step was to install the Rust toolchain using the following commands, and selecting option 1 to proceed with the standard installation.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shYou will now need to update the shell you are currently in, so I did (there is a space after the initial dot)
. "$HOME/.cargo/env"and then
rustup default stableinfo: using existing install for 'stable-x86_64-unknown-linux-gnu'info: default toolchain set to 'stable-x86_64-unknown-linux-gnu'stable-x86_64-unknown-linux-gnu unchanged - rustc 1.85.1 (4eb161250 2025-03-15)4/ We need to install some additional Rust tools that are needed to build the gui stuff (this takes a few minutes)
cargo install --version 1.6.2 tauri-cli5/ We next install Python tools needed
curl --retry 5 --proto '=https' --tlsv1.2 -sSf https://mise.run | shecho "eval \"\$(/home/ubuntu/.local/bin/mise activate bash)\"" >> ~/.bashrcecho 'eval "$(mise activate bash)"' >> ~/.bashrcbashmake sure we are in the right directory (you should be in amazon-q-developer-cli, the repo you cloned)
mise trustwhich should output
mise trusted /home/ubuntu/amazon-q-developer-cliand then
mise installwhich will install a bunch of packages
mise hint use multiple versions simultaneously with mise use python@3.12 python@3.11mise hint installing precompiled python from astral-sh/python-build-standaloneif you experience issues with this python (e.g.: running poetry), switch to python-build by running mise settings python.compile=1gpg: Signature made Tue Feb 11 10:44:53 2025 UTCgpg: using RSA key C0D6248439F1D5604AAFFB4021D900FFDB233756gpg: Good signature from "Antoine du Hamel <duhamelantoine1995@gmail.com>" [unknown]mise node@22.14.0 ✓ installedmise python@3.11.11 ✓ installed6/ More tools to install
curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=$(jq -r '.packageManager' package.json | cut -d@ -f2 | cut -d+ -f1) SHELL=$(which bash) sh -which will output something similar to:
==> Downloading pnpm binaries 10.0.0 WARN using --force I sure hope you know what you are doingCopying pnpm CLI from /tmp/tmp.hq956QfOS9/pnpm to /home/ubuntu/.local/share/pnpm/pnpmAppended new lines to /home/ubuntu/.bashrcNext configuration changes were made:export PNPM_HOME="/home/ubuntu/.local/share/pnpm"case ":$PATH:" in *":$PNPM_HOME:"*) ;; *) export PATH="$PNPM_HOME:$PATH" ;;esacTo start using pnpm, run:source /home/ubuntu/.bashrcand we oblige by typing
source /home/ubuntu/.bashrc7/ Now we install the Python dependencies the build scripts will use
corepack enablepip install --upgrade pippip3 install -r build-scripts/requirements.txtWe are now ready to build the packages, which thanks to the help of the Python scripts is as simple as running these commands:
export AMAZON_Q_BUILD_SKIP_FISH_TESTS=1export AMAZON_Q_BUILD_SKIP_SHELLCHECK_TESTS=1export GNOME_SHELL_BUILD_RELEASE=1python3.11 build-scripts/main.py build --variant=fullWhich will start the build process - perfect time for a cup of tea!
INFO: Building for prodINFO: Release: TrueINFO: Cargo features: {'q_cli': ['wayland']}INFO: Signing app: FalseINFO: Variants: ['FULL']INFO: Building npm packages+ pnpm install --frozen-lockfileScope: all 18 workspace projects......The process too my EC2 instance around 15 minutes to complete. You can see the sped up version here so you can compare it to your own.
When it completes, you will have the Amazon Q Developer CLI binaries in the build directory.
-rw-rw-r-- 1 ubuntu ubuntu 43297 Mar 23 13:32 vscode-plugin.vsixdrwxr-xr-x 3 ubuntu ubuntu 4096 Mar 23 13:32 autocompletedrwxr-xr-x 5 ubuntu ubuntu 4096 Mar 23 13:32 dashboarddrwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 13:56 bin-rw-rw-r-- 1 ubuntu ubuntu 124037071 Mar 23 13:56 q.tar.gz-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 13:56 q.tar.gz.sha256-rw-rw-r-- 1 ubuntu ubuntu 108726532 Mar 23 13:58 q.tar.xz-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 13:58 q.tar.xz.sha256-rw-rw-r-- 1 ubuntu ubuntu 110606256 Mar 23 13:59 q.tar.zst-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 13:59 q.tar.zst.sha256-rw-rw-r-- 1 ubuntu ubuntu 124031917 Mar 23 13:59 q.zip-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 13:59 q.zip.sha256drwxrwxr-x 20 ubuntu ubuntu 4096 Mar 23 13:59 ..drwxrwxr-x 4 ubuntu ubuntu 4096 Mar 23 14:13 themesdrwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 amazon-q-for-cli-legacy-gnome-integration@aws.amazon.comdrwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 amazon-q-for-cli-gnome-integration@aws.amazon.comdrwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 appImage-metadatadrwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:19 deb-metadatadrwxrwxr-x 4 ubuntu ubuntu 4096 Mar 23 14:19 linux-bundles-rw-r--r-- 1 ubuntu ubuntu 179909694 Mar 23 14:19 amazon-q.deb-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 14:19 amazon-q.deb.sha256-rwxr-xr-x 1 ubuntu ubuntu 335942848 Mar 23 14:19 amazon-q.appimage-rw-rw-r-- 1 ubuntu ubuntu 64 Mar 23 14:19 amazon-q.appimage.sha256If I wanted I could also do minimal setups that are perfect for headless systems by typing the following:
python3.11 build-scripts/main.py build --variant=minimal8/ You will now be able to grab your binaries and/or packages and deploy them on your GUI or headless environments. In this short video below I show grabbing the debian package and then installing it in my EC2 based Ubuntu Desktop machine.
I encountered one error when compiling on Ubuntu (which I did not get on Amazon Linux 2023), but it was a false positive and due to be building via a remote ssh connection. If you see the following error when trying to build the software, where it fails during the tests with this stack trace:
failures:
---- directories::linux_tests::all_paths stdout ----thread 'directories::linux_tests::all_paths' panicked at crates/fig_util/src/directories.rs:546:9:assertion failed: remote_socket_path().is_ok()note: run with `RUST_BACKTRACE=1` environment variable to display a backtracefailures: directories::linux_tests::all_pathstest result: FAILED. 21 passed; 1 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.09serror: test failed, to rerun pass `-p fig_util --lib`I made the following change to "crates/fig_util/src/directories.rs"
- 546 : assert!(remote_socket_path().is_ok());+ 546:+ 547: // Skip remote_socket_path check if we're in a test environment without Q_PARENT set+ 548: // This allows tests to pass in CI environments+ 549: if std::env::var_os(Q_PARENT).is_some() || !is_remote() || in_cloudshell() {+ 550: assert!(remote_socket_path().is_ok());+ 551: }+ 552: 547, 553: assert!(local_remote_socket_path().is_ok());When I made that change, the issue was resolved.
If your build does break, when you try and run it again you may encounter this error
+ cargo clippy --locked --workspace --exclude zbus --exclude zbus_names --target x86_64-unknown-linux-gnu --exclude fig_desktop --exclude fig_desktop-fuzz --features waylanderror: the lock file /home/ubuntu/amazon-q-developer-cli/Cargo.lock needs to be updated but --locked was passed to prevent thisIf you want to try to generate the lock file without accessing the network, remove the --locked flag and use --offline instead.Traceback (most recent call last): File "/home/ubuntu/amazon-q-developer-cli/build-scripts/main.py", line 113, in <module> build( File "/home/ubuntu/amazon-q-developer-cli/build-scripts/build.py", line 829, in build run_clippy(variants=variants, features=cargo_features, target=cargo_test_target) File "/home/ubuntu/amazon-q-developer-cli/build-scripts/test.py", line 34, in run_clippy run_cmd( File "/home/ubuntu/amazon-q-developer-cli/build-scripts/util.py", line 95, in run_cmd subprocess.run(args, env=env, cwd=cwd, check=check) File "/home/ubuntu/.local/share/mise/installs/python/3.11.11/lib/python3.11/subprocess.py", line 571, in run raise CalledProcessError(retcode, process.args,subprocess.CalledProcessError: Command '['cargo', 'clippy', '--locked', '--workspace', '--exclude', 'zbus', '--exclude', 'zbus_names', '--target', 'x86_64-unknown-linux-gnu', '--exclude', 'fig_desktop', '--exclude', 'fig_desktop-fuzz', '--features', 'wayland']' returned non-zero exit status 101.You can run cargo update which should clear the error and allow you to proceed.
Whether you are running Amazon Q Developer CLI locally or headless, you will need to make sure that you keep up to date with the latest versions as they are released. You can get more info about changes by checking out the release notes in the GitHub repo.
When a new version is available, you will get notified when running the tool:
A new version of q is available: 1.7.2Run q update to update to the new versionFrom the command line this is super easy to do:
q updateWhich should result in a progress bar showing, and then (hopefully) success.
[ec2-user@ip-172-31-29-188 ~]$ q update███████████████████████████████████████ 100/100Whilst I can happily use Amazon Q Developer CLI now, I did run into a few errors so sharing those here.
Whilst I was using Amazon Q Developer on a remote Linux host, when I ran "q doctor" to check that the installation looked good, I ran into this error
[ec2-user@ip-172-31-29-188 ~]$ q doctor✘ Qterm Socket Check: Qterm is not running, please restart your terminal. QTERM_SESSION_ID is unset.✘ Doctor found errors. Please fix them and try again.What resolved this issue for me, was to run the following on my LOCAL machine (where I had ssh'd from)
q integrations install sshWhen I then re-ran the command, I got the following:
[ec2-user@ip-172-31-29-188 ~]$ q doctor -v● Could not read sshd_config, check https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-autocomplete-ssh.html for more info✔ Everything looks good!(you can ignore the sshd_config message - this has been reported here) and is a false positive.
(As an aside, you can run "q doctor -a" to get a more detailed breakdown)
[ec2-user@ip-172-31-29-188 ~]$ q doctor --allLet's check if you're logged in...✔ AuthLet's check your dotfiles...✔ bash ~/.bashrc integration check✔ bash ~/.bash_profile integration checkLet's make sure Amazon Q is set up correctly...✔ Amazon Q data dir exists✔ PATH contains ~/.local/bin✔ Amazon Q settings corruption● Could not read sshd_config, check https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-autocomplete-ssh.html for more info✔ Amazon Q terminal integrationsLet's see if the app is in a working state...✔ Qterm Socket Check✔ Autocomplete dev mode✔ Plugin dev mode✔ Dashboard is loading from the correct URL✔ Autocomplete is loading from the correct URLLet's check if your system is compatible...✔ OS is supported✔ Bash is up to date✔ Fish is up to dateAnother error you might see when doing q doctor is
ubuntu@ip-172-31-29-8:~$ q doctor● GTK_IM_MODULE is not set to `ibus`. This may cause autocomplete to break in some terminals.✔ Everything looks good! Amazon Q still not working? Run q issue to let us know!There is another issue logged here and I set an env variable (export GTK_IM_MODULE=ibus) in my .bashrc and this then resolved the issue.
In Ubuntu, GTK_IM_MODULE is an environment variable that tells GTK applications which input method module to use for handling text input. There are different options, which also change depending on which versions of Ubuntu you are using and which graphics manager (X or Wayland).
In this post I introduced different ways you can install Amazon Q Developer CLI on your Linux environments. Whether they are your local desktop environments or remote headless systems, you can install and have Amazon Q Developer CLI available to you wherever you work.
This blog post just touched the surface of what AI Coding Assistants like Amazon Q Developer can do, and keep posted as I will be sharing more examples as well as tips in future.
You can try Amazon Q Developer CLI for free today, by signing up for a Builder ID and then downloading the app from here.
Until next time folks!
Made with 🧡 by DevRel!
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.
Comments
Log in to comment