Whether you are running a GUI Linux distribution or accessing a remote headless Linux system, having Amazon Q Developer at your finger tips is only a few steps away
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.
Warning! Before proceeding I want to caveat that apart from the official installation methods, the stuff below is not part of any officially supported solution. I am sharing incase others are interested in getting Amazon Q Developer up and running in their own environments.
Setting up your Builder ID
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).
Installing on local Linux distributions
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.
Via AppImage
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 libfuse2
2/ 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.appimage
3/ Make it executable
chmod +x amazon-q.appimage
You 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.
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.
Via the Debian package
1/ Install dependencies (this is only needed for Ubuntu)
sudo apt install libfuse2
2/ 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.deb
3/ Install the package
sudo apt install -y ./amazon-q.deb
4/ Open up Amazon Q Developer and follow installation instructions
q
When 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.
Uninstalling
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 uninstall
If you installed via the debian package, then you can use the following command:
sudo apt purge amazon-q
Installing on headless (remote) Linux distributions
In this setup we are going to install Amazon Q Developer CLI on a remote, headless Linux system.
Dependencies
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 --version
ldd (GNU libc) 2.34
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; 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.
Full vs Chat
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.
Complete the local setup
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 ssh
When 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.
Installing on the 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 yes
You should restart sshd using
sudo systemctl restart sshd
Disconnect 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.
For Ubuntu 2024 I used this
sudo apt-get install gnupg
If 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 libfuse2
4/ 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.zip
Note! 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.pem
Download 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.zip
Note 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.zip
7/ Run the installation script
chmod +x q/install.sh
./q/install.sh
And then follow the prompts.
? Select login method ›
❯ Use for Free with Builder ID
Use with Pro license
Confirm the following code in the browser
Code: PNDN-QVKB
Open 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 successfully
8/ You can now validate that Amazon Q Developer CLI is up and running by running the "q doctor".
q doctor
Note! 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
Uninstalling
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
Compiling from source
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 managers
If 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
git clone https://github.com/aws/amazon-q-developer-cli.git
cd amazon-q-developer-cli
2/ 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 update
sudo 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 zip
I 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 | sh
You 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 stable
info: 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-cli
5/ We next install Python tools needed
curl --retry 5 --proto '=https' --tlsv1.2 -sSf https://mise.run | sh
echo "eval \"\$(/home/ubuntu/.local/bin/mise activate bash)\"" >> ~/.bashrc
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
bash
make sure we are in the right directory (you should be in amazon-q-developer-cli, the repo you cloned)
mise trust
which should output
mise trusted /home/ubuntu/amazon-q-developer-cli
and then
mise install
which will install a bunch of packages
mise hint use multiple versions simultaneously with mise use python@3.12 python@3.11
mise hint installing precompiled python from astral-sh/python-build-standalone
if you experience issues with this python (e.g.: running poetry), switch to python-build by running mise settings python.compile=1
gpg: Signature made Tue Feb 11 10:44:53 2025 UTC
gpg: using RSA key C0D6248439F1D5604AAFFB4021D900FFDB233756
gpg: Good signature from "Antoine du Hamel <duhamelantoine1995@gmail.com>" [unknown]
mise node@22.14.0 ✓ installed
mise python@3.11.11 ✓ installed
6/ 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 doing
Copying pnpm CLI from /tmp/tmp.hq956QfOS9/pnpm to /home/ubuntu/.local/share/pnpm/pnpm
Appended new lines to /home/ubuntu/.bashrc
Next configuration changes were made:
export PNPM_HOME="/home/ubuntu/.local/share/pnpm"
case ":$PATH:" in
*":$PNPM_HOME:"*) ;;
*) export PATH="$PNPM_HOME:$PATH" ;;
esac
To start using pnpm, run:
source /home/ubuntu/.bashrc
and we oblige by typing
source /home/ubuntu/.bashrc
7/ Now we install the Python dependencies the build scripts will use
corepack enable
pip install --upgrade pip
pip3 install -r build-scripts/requirements.txt
Ready to build
We 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=1
export AMAZON_Q_BUILD_SKIP_SHELLCHECK_TESTS=1
export GNOME_SHELL_BUILD_RELEASE=1
python3.11 build-scripts/main.py build --variant=full
Which will start the build process - perfect time for a cup of tea!
INFO: Building for prod
INFO: Release: True
INFO: Cargo features: {'q_cli': ['wayland']}
INFO: Signing app: False
INFO: Variants: ['FULL']
INFO: Building npm packages
+ pnpm install --frozen-lockfile
Scope: 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.vsix
drwxr-xr-x 3 ubuntu ubuntu 4096 Mar 23 13:32 autocomplete
drwxr-xr-x 5 ubuntu ubuntu 4096 Mar 23 13:32 dashboard
drwxrwxr-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.sha256
drwxrwxr-x 20 ubuntu ubuntu 4096 Mar 23 13:59 ..
drwxrwxr-x 4 ubuntu ubuntu 4096 Mar 23 14:13 themes
drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 amazon-q-for-cli-legacy-gnome-integration@aws.amazon.com
drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 amazon-q-for-cli-gnome-integration@aws.amazon.com
drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:13 appImage-metadata
drwxrwxr-x 2 ubuntu ubuntu 4096 Mar 23 14:19 deb-metadata
drwxrwxr-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.sha256
If 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=minimal
8/ 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.
Compiling Errors
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 backtrace
failures:
directories::linux_tests::all_paths
test result: FAILED. 21 passed; 1 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.09s
error: 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 wayland
error: the lock file /home/ubuntu/amazon-q-developer-cli/Cargo.lock needs to be updated but --locked was passed to prevent this
If 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.
Updating Amazon Q Developer CLI
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.2
Run q update to update to the new version
From the command line this is super easy to do:
q update
Which should result in a progress bar showing, and then (hopefully) success.
[ec2-user@ip-172-31-29-188 ~]$ q update
███████████████████████████████████████ 100/100
Errors
Whilst I can happily use Amazon Q Developer CLI now, I did run into a few errors so sharing those here.
q doctor fails
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 ssh
When 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 --all
Let's check if you're logged in...
✔ Auth
Let's check your dotfiles...
✔ bash ~/.bashrc integration check
✔ bash ~/.bash_profile integration check
Let'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 integrations
Let'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 URL
Let's check if your system is compatible...
✔ OS is supported
✔ Bash is up to date
✔ Fish is up to date
Another 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).
Conclusion
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.
Get started with Amazon Q Developer
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!
(image generated with Amazon Nova using the prompt: create a pixel art image of a linux penguin that is cuddling a giant letter Q - the colour theme should be muted blue)
Top comments (0)