Install Qwen Code on Linux, macOS, or Windows

What Qwen Code is and how this workflow fits together

Qwen Code is an open-source agentic coding tool designed primarily for terminal use. In its normal interactive workflow, you open a terminal in a project directory, run qwen, and communicate with the agent using natural-language requests. The agent can examine the repository context and assist with tasks such as explaining an unfamiliar codebase, planning work, and implementing changes, subject to its configured tools, permissions, model provider, and approval settings.

Installation and network exposure are separate concerns. Installing the command-line application does not create a remotely accessible service. The ordinary qwen command launches an interactive terminal interface, while qwen -p "..." is documented for noninteractive scripts, CI/CD, and batch processing. The distinct qwen serve mode starts an experimental shared agent session over HTTP and Server-Sent Events using ACP. Only that daemon workflow provides the network service relevant to an HTTP tunnel.

This ordering matters. First install Qwen Code, authenticate it, and confirm ordinary terminal operation. Next start and inspect the daemon locally. Only after identifying its actual listener and access controls should you configure remote connectivity. A tunnel cannot repair an application that is not running, listening on the wrong interface, or failing provider authentication.

Prerequisites and installation choices

You need a supported Linux, macOS, or Windows environment with a terminal. Windows users following the standalone command need PowerShell. Linux and macOS users following the standalone command need curl and a shell capable of running the downloaded installer. You also need access to a model provider supported by the Qwen Code authentication menu and the credentials required by that provider.

Run Qwen Code from a repository or project directory whose files you are prepared to let the agent inspect. Review the project's trusted-folder, approval, sandboxing, ignored-file, and provider settings before using it with sensitive source code. Do not paste provider API keys into source files, shell history, screenshots, issue reports, or tunnel configuration.

Install Qwen Code on Linux, macOS, or Windows

Choose one installation method. Do not install the same executable through several package managers unless you intentionally manage the resulting path precedence. Multiple installations can leave an older binary earlier on PATH, making updates appear ineffective.

Option 1: Install the standalone build on Linux or macOS

Open a terminal and run the official standalone installer:

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

The installer uses a standalone archive when one is available for the platform. If it needs to fall back to npm, Node.js 22 or later and npm must already be available on PATH. When installation finishes, restart the terminal so that environment changes are loaded.

Option 2: Install the standalone build on Windows

Open PowerShell and run the official Windows installer:

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Close and reopen PowerShell or your preferred terminal after the installer completes. This is particularly important when the installer has changed environment variables or added the executable location to PATH.

Option 3: Install globally with npm

Confirm that Node.js 22 or later and npm are installed, then install the latest Qwen Code package globally:

npm install -g @qwen-code/qwen-code@latest

Global npm installation locations differ according to operating system, Node.js distribution, version manager, and npm configuration. If installation succeeds but qwen is unavailable, diagnose the global npm executable path rather than repeatedly reinstalling the package.

Option 4: Install with Homebrew

On a Linux or macOS system with Homebrew already configured, run:

brew install qwen-code

Keep future upgrades consistent with the selected package manager. If Homebrew installed the active executable, update it through Homebrew rather than placing an npm-managed copy over it.

Option 5: Prepare an offline installation

Qwen Code documents an offline approach based on a release archive. Download the appropriate official release archive and retain the matching SHA256SUMS file beside it. The installer supports an --archive PATH argument. The exact archive filename and platform artifact must come from the release you are installing, so this guide does not invent a filename or checksum command.

Verify that the archive and checksum information belong to the same release before installation. In an enterprise workflow, preserve the downloaded artifact, checksum record, approval decision, and installed version so the deployment can be reproduced and audited.

Launch Qwen Code and configure a model provider

Installation provides the client, but the coding agent still needs a model provider. Start from the project you want Qwen Code to understand. Replace the example directory with your real project path:

cd your-project
qwen

On first launch, Qwen Code prompts you to connect a provider. The documented menu includes Alibaba ModelStudio, third-party providers, and a custom provider. Available details can change with the installed Qwen Code version and provider, so follow the prompts shown by your client rather than copying an API key format from an unrelated provider.

Verify the installation before enabling daemon mode

A useful verification checks more than whether the executable starts. Confirm command discovery, interactive launch, provider connectivity, workspace selection, and a harmless request. This isolates ordinary installation problems before network listening or tunneling adds more variables.

Check command discovery

Open a new terminal and ask the executable for its help output:

qwen --help

Successful help output shows that the shell can locate and launch the executable. It does not prove that provider credentials are valid. If the shell reports that the command cannot be found, restart it, inspect PATH, and check whether a different installation of Qwen Code is shadowing the expected one.

Check the interactive workflow

Enter a known project directory and run:

qwen

Complete authentication if prompted. Begin with a read-only explanation request and inspect the response for the expected repository context. If Qwen Code opens but the request fails, separate client startup from provider connectivity. Typical categories include missing credentials, a provider-specific account problem, an incorrect custom endpoint, model availability, or blocked outbound network access.

Optionally check headless execution

The documented headless form is:

qwen -p "Summarize this project."

Run it from a non-sensitive test project. Headless operation is useful for scripts and CI/CD, but it can inherit access to the current working directory and environment. Treat automation credentials and permissions with the same care as an interactive session.

Routine operation, updates, and removal

Start Qwen Code from the project directory relevant to the task. The current directory determines important workspace context, so verify it before requesting analysis or approving file operations. Use interactive mode for terminal conversations and headless mode only when a script genuinely needs noninteractive output.

Keep one installation source authoritative. The appropriate update command depends on how Qwen Code was installed:

After an update, open a new terminal and repeat the help, interactive authentication, and low-risk project checks. Experimental daemon behavior can change between releases, even when a release reports no known breaking changes. Validate the daemon listener, protocol compatibility, authentication model, and client behavior again before restoring public access.

Stopping an interactive terminal session and stopping a daemon are different operations. A running qwen serve process may continue until it is explicitly terminated or its process supervisor stops it. Similarly, stopping Qwen Code does not automatically delete a Localtonet tunnel configuration, and creating a tunnel does not mean it is currently running.

Start and inspect the experimental Qwen Code daemon locally

Qwen Code documents qwen serve as an experimental daemon that provides a shared agent session over HTTP+SSE using ACP, allowing multiple clients to interact with one agent. This is the mode to evaluate if you need a network-accessible Qwen Code service.

qwen serve

Run the command from the intended workspace and keep its terminal output visible. Record the listener information and any security or client instructions printed by the installed version. The supplied project evidence confirms the command and protocol family, but it does not establish one universal hostname, port, bind address, authentication mechanism, health endpoint, browser route, or remote-client configuration.

That missing information is security-critical. Do not substitute a popular development port, assume the service listens on 127.0.0.1, or assume it binds to all interfaces. Do not assume that opening the base URL in a browser is a valid protocol test. HTTP+SSE and ACP clients may require specific endpoints, methods, headers, event handling, session identifiers, or protocol versions.

Local daemon validation checklist

• Confirm that qwen serve remains running rather than exiting with a configuration or authentication error.
• Read the startup output for the actual listener address and port.
• Consult the daemon documentation matching the installed release for its authentication and security model.
• Confirm whether the listener is loopback-only or available on other local interfaces.
• Use a compatible ACP client or the documented protocol test, rather than inventing an HTTP path.
• Verify that a client can create or join only the sessions it is meant to access.
• Test disconnect and reconnect behavior before relying on a remote workflow.
• Understand what workspace files, tools, commands, extensions, and model credentials the daemon can reach.

Expose a verified Qwen Code daemon with a Localtonet HTTP tunnel

Once the daemon works locally and you have confirmed its security model, an HTTP tunnel is the relevant Localtonet tunnel family because Qwen Code identifies daemon mode as HTTP+SSE. Our client runs on the computer that hosts Qwen Code, or on a device that can reach its verified local listener. The client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

The Localtonet public URL forwards traffic to the configured local IP address and port. It does not choose the Qwen Code port, start the daemon, configure ACP, create daemon authentication, or convert an incompatible web browser into an ACP client. The daemon must already be running and reachable from the Localtonet client device.

For the current dashboard workflow and field definitions, review our Localtonet HTTP tunnel documentation. The exact Qwen Code local target must still come from the installed daemon, not from the tunnel documentation.

Remote verification without guessing protocol details

Start by checking the Localtonet dashboard state: the device should be connected and the tunnel should be running. Then inspect the Qwen Code daemon log while a compatible remote client attempts to connect. This distinguishes several failure classes:

• No request in the daemon log usually points toward tunnel state, device connectivity, the selected relay, DNS, or the remote client's URL.
• A connection reaching the daemon but receiving an HTTP error points toward an incorrect ACP path, method, header, protocol version, or daemon-side authorization.
• An SSE connection that opens and repeatedly drops can indicate client compatibility, proxy timeout expectations, daemon errors, or network interruption.
• A successful connection followed by provider errors indicates that the HTTP path works but the daemon cannot complete model operations.
• A session connected to the wrong workspace indicates that the daemon was started from an unintended directory or with the wrong workspace configuration.

Do not test an unknown endpoint by sending credentials or destructive agent requests. Begin with the documented connection handshake and a harmless read-only task. Review the active workspace and session identity before allowing edits or command execution.

Troubleshooting installation, authentication, daemon, and tunnel problems

qwen is not found after installation

Restart the terminal first because the installer may have changed environment variables. If the problem remains, check whether the installation completed successfully and whether its executable directory is on PATH. With npm, also verify that Node.js is version 22 or later and that npm's global executable location is available to the shell. Avoid reinstalling through another package manager until you understand which executable path should be active.

The standalone installer fails during an npm fallback

The standalone installer can fall back to npm when a standalone archive is unavailable for the platform. Install or activate Node.js 22 or later, ensure npm is on PATH, open a new terminal, and retry. In a restricted network, verify access to the required official asset and package endpoints. For an offline environment, use the official release archive workflow with its matching SHA256SUMS.

Qwen Code starts but model requests fail

Reopen /auth and confirm the selected provider. Check the provider-specific credential, account status, endpoint, model access, and outbound network policy. If using a custom provider, verify its documented API compatibility instead of assuming that any HTTP model endpoint will work. Keep provider failures separate from daemon and Localtonet troubleshooting.

qwen serve exits immediately

Read the terminal error before changing tunnel settings. The Localtonet tunnel cannot keep a failed daemon alive. Confirm that ordinary qwen operation and provider authentication work, then check the daemon documentation for the installed release. Do not add guessed flags or environment variables.

The daemon runs, but its port is unclear

Inspect the startup output and the version-matched daemon configuration reference. If neither establishes a listener, do not create a tunnel based on a guessed default. Confirm that the installed package actually includes the documented experimental daemon mode and that no process supervisor is hiding its output.

The Localtonet URL does not connect

Verify the dependency chain in order: Qwen Code daemon process, local listener, local ACP client, Localtonet client connection, selected device, tunnel configuration, tunnel Start state, and remote-client URL. Ensure that the tunnel targets the exact local IP and port reachable from the Localtonet client device. A loopback address works only when our client runs in the same network namespace as the daemon.

A browser shows an error or blank response

A browser request to the public origin is not necessarily a valid ACP test. The daemon uses HTTP+SSE, and the actual client may need documented paths, methods, headers, session operations, or protocol negotiation. Use the supported remote client and the Qwen Code HTTP protocol documentation for the installed version.

Local access works, but remote SSE disconnects

Confirm that the tunnel remains running and that the Localtonet client remains connected. Inspect both client and daemon logs around the disconnect. Check the ACP client's reconnect behavior and Qwen Code's SSE event and session-lifecycle requirements. Do not assume that ordinary short HTTP request behavior is sufficient for a long-lived event stream.

An update appears to have had no effect

You may be launching a different copy of qwen than the one updated. This commonly occurs when standalone, npm, and Homebrew installations coexist. Inspect shell command resolution and remove obsolete installations through their original package manager only after confirming which copy is active.

Frequently asked questions