The essential guide to installing Amazon Q Developer CLI on Windows
Ricardo Sueiras

Ricardo Sueiras @094459

About: Technologist/Maker/Builder. Developer Advocate at AWS, specialising in open source. Find me on Mastadon at https://hachyderm.io/@094459

Location:
London
Joined:
Sep 2, 2019

The essential guide to installing Amazon Q Developer CLI on Windows

Publish Date: Mar 31
136 9

Following on from my previous post on how to install Amazon Q Developer CLI on Linux environments, I thought I would share a similar guide for those of you using Windows.

Whilst there is no native Windows installation yet, you can install and run Amazon Q Developer CLI on your Windows machines using the Windows Subsystem for Linux, or wsl for short. In this post I will walk you through what you need to do.

Installing wsl

You might already have wsl installed on your machine, in which case you can skip this step. If you do not, then Microsoft have put together a blog post that walks you through this process. To summarise this, you need to run the following from a command prompt.

wsl --install
Enter fullscreen mode Exit fullscreen mode

Once you have wsl up and running we can begin.

Installing Amazon Q Developer CLI

Before proceeding, make sure you have already setup wsl on your Windows machine (see the doc linked above).

From a Windows command shell enter the following command:

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

This is going to download and install a virtual Ubuntu instance in your wsl environment. If you have already done this in the past, it will just log you into your Ubuntu wsl environment.

After installing Ubuntu, you will be asked to create a default user account (that will typically copy the name of the Windows user you are logged in as), and then enter a password. After you have completed that you are all ready to go.

You will notice that the default directory when you are in your wsl account maps to your Windows home directory.

For the installation we will change this and enter the home directory of the wsl environment, which we can do by simply typing:

cd
Enter fullscreen mode Exit fullscreen mode

You will notice that the directory path has changed.

The first thing we need to do is install some missing packages that the installation will need. We will use the native package manager of Ubuntu to do this.

sudo apt install unzip
Enter fullscreen mode Exit fullscreen mode

You will be asked to enter the password for the Ubuntu user you created (not the Windows password, unless of course you used the same one!). This will install the unzip utility and should not take long.

The next step is to download the zip file that contains the installer. From the wsl command line, we use the following command:

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip" -o "q.zip"
Enter fullscreen mode Exit fullscreen mode

This should download the installer into your current directory, which should be the home directory.

Make sure you check! that you are running in the wsl home directory and not the windows home directory. If you use the "pwd" command, it will tell you. It should say "/home/{youruser}" - if it does not, then make sure you enter the "cd" command again.

Now we will unzip this by using the following command:

unzip q.zip
Enter fullscreen mode Exit fullscreen mode

Which creates a subdirectory called "q" with all the files we need. We are nearly ready to run the installer, but first we need to enable it by running the following commands:

cd q
chmod +x install.sh
Enter fullscreen mode Exit fullscreen mode

The chmod command changes permissions of files in Linux, and we are enable the install.sh to be executable so we can run the installer. Which we do using the following command:

./install.sh
Enter fullscreen mode Exit fullscreen mode

You will be asked if you want it to modify your shell config. Answer "Yes" as what this is doing is adding a new path to point to the Amazon Q Developer CLI executables. Once that has completed, you will now need to activate your new shell. You can either exit and re-launch your wsl environment, or just type:

bash
Enter fullscreen mode Exit fullscreen mode

Amazon Q Developer is now installed, the next stage us to create our Builder ID and then use it to login.

Logging into Amazon Q Developer using a Builder ID

From the command enter the following command:

q login
Enter fullscreen mode Exit fullscreen mode

You will see two options for Login method which you can select using the up and down arrow keys. You want to select the first option, "Use for Free with Builder ID"

When you select this option, it will ask you to open a URL in a web browser. Copy the URL, and then open it up in a web browser. You will now need to either create a new Builder ID, or login using an existing Builder ID you might already have.

I have created a short video that shows you these steps.

Once you have completed that, you will be logged into Amazon Q Developer and can access it from wsl by invoking:

q chat
Enter fullscreen mode Exit fullscreen mode

Congratulations, you are now ready to go!

In the video you will also see me running "q doctor" which is a way to check to see that everything is running ok with Amazon Q Developer.

Hello World

Now that we have Amazon Q Developer installed, we can start using it by starting a new wsl session, and then invoking it using the "q chat" or "q ai" commands.

We start our wsl session:

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

If you notice that in my session, the default directory is the Windows home directory. If I invoke Amazon Q Developer cli here, then this is going to be its working directory.

I can now invoke Amazon Q Developer CLI using the following command:

q chat
Enter fullscreen mode Exit fullscreen mode

And I now have access to all the features and capabilities of Amazon Q Developer. In this example video, I show how I can use it to create a simple Windows batch file that I run from a native Windows command shell.

After I have completed my activities, I can exit from Amazon Q Developer by typing "/q", and then leave my wsl session any time entering "exit"

Conclusion

In this post I shared how you can install Amazon Q Developer CLI on your Windows machine using the Windows Subsystem for Linux, and showed you how you can get started.

Get started with Amazon Q Developer

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!

Comments 9 total

  • kowalsk
    kowalskJul 12, 2025

    This is great, thank you for taking the time to do this, it got me started in no time :)

  • Saran Tanpituckpong
    Saran TanpituckpongAug 5, 2025

    No native Windows PowerShell support? 😢

    • Ricardo Sueiras
      Ricardo SueirasAug 6, 2025

      No, although if you check out the demo video, you can see that I create powershell scripts within wsl when using Amazon Q CLI, so it is possible just not in the same terminal session. Watch this space though, as there is a native Windows installer on the roadmap, and so hopefully this will come along soon. In the meantime, as this is an open source project I am aware of a few folk who have compiled windows native binaries. Check out this repo and see if this works for you -> github.com/DiscreteTom/amazon-q-de...

      • Uhsarp A
        Uhsarp AAug 8, 2025

        Nice try. Wnidows defender detects a virus.

        • Ricardo Sueiras
          Ricardo SueirasAug 8, 2025

          ahh really, ok I will make sure that I dont recommend that link to others. One colleague tried to run it and said it didnt do anything (just got back to me an hour ago). Man, need to get myself a windows machine.

  • Uhsarp A
    Uhsarp AAug 8, 2025

    It worked fine when I installed it yesterday.
    Today when I try to open chat, it asked for login. While logging in, I get this error

    q/bin$ q login
    ✔ Select login method · Use for Free with Builder ID
    error: dispatch failure

    • Ricardo Sueiras
      Ricardo SueirasAug 8, 2025

      Mmmm, I will check this out. Not seen that message before.

    • Ricardo Sueiras
      Ricardo SueirasAug 8, 2025

      Ok a couple of things to try. First of all, can you try "q logout" and then try and login from scratch to see if that fixes the issue. If that does not work, can you see if you are running the latest version of Q CLI, which you can find by running "q update". If you are running the latest version, then the only other thing I can think of is that it might be a service degradation issue. If you can try later and see if you get the same error and let me know.

  • HP-85
    HP-85Aug 14, 2025

    Great article - thank you!

    The instructions in the Q CLI User Guide - Installing with a zip file - seems to work for installing on WSL in both Windows 11 x64 and arm64.

    Here's an example of using Q CLI from WSL to interact with Windows:

    > how do I query windows system event log for event ID 6009

> You can query the Windows System Event Log for event ID 6009 from WSL using PowerShell. Here are several approaches:
## Using Get-WinEvent (recommended)
bash
powershell.exe -Command "Get-WinEvent -FilterHashtable @{LogName='System'; ID=6009}"

 ● I will run the following shell command:
powershell.exe -Command "Get-WinEvent -FilterHashtable @{LogName='System'; ID=6009}"
 ⋮
 ↳ Purpose: Query Windows System Event Log for event ID 6009 using PowerShell Get-WinEvent
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:
> y
   ProviderName: EventLog

TimeCreated                      Id LevelDisplayName Message
-----------                      -- ---------------- -------
8/7/2025 9:41:26 AM            6009 Information      Microsoft (R) Windows (R) 10.00. 22631  Multiprocessor Free.
8/6/2025 12:13:42 PM           6009 Information      Microsoft (R) Windows (R) 10.00. 22631  Multiprocessor Free.
8/5/2025 8:07:40 AM            6009 Information      Microsoft (R) Windows (R) 10.00. 22631  Multiprocessor Free.
    Enter fullscreen mode Exit fullscreen mode
Add comment