qwen-code/docs/users/quickstart.md

Quickstart

👏 Welcome to Qwen Code!

This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.

Before you begin

Make sure you have:

• A terminal or command prompt open
• A code project to work with
• One of the following:
  • A Qwen account with a Plus or Pro subscription from chat.qwen.ai, which unlocks access to Qwen Code and Agent
  • An API key or Token Plan subscription from 千问AI平台 / QwenCloud (China / International) — the recommended setup
  • An API key from Alibaba Cloud ModelStudio (Beijing / intl)
  • An Alibaba Cloud Token Plan (Beijing / intl) subscription

Step 1: Install Qwen Code

To install Qwen Code, use one of the following methods:

Quick Install (Recommended)

Linux / macOS

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

Windows

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

Note

It's recommended to restart your terminal after installation to ensure environment variables take effect.

Manual Installation

Prerequisites

Make sure you have Node.js 22 or later installed. Download it from nodejs.org.

NPM

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

Homebrew (macOS, Linux)

brew install qwen-code

Step 2: Set up authentication

When you start an interactive session with the qwen command, you'll be prompted to configure authentication:

# You'll be prompted to set up authentication on first use
qwen

# Or run /auth anytime to change authentication method
/auth

The first-run menu lets you connect a model provider. Choose one of:

• Qwen Account with Subscription — sign in with your Qwen account to access Qwen Code and Agent with your Plus or Pro subscription. If you don’t have a subscription yet, visit chat.qwen.ai to subscribe to Plus or Pro, then return to Qwen Code and select Qwen Account with Subscription.

• QwenCloud — the recommended setup. Opens a sub-menu:

  • Token Plan: subscription with a monthly Credit quota on a dedicated endpoint (Personal and Team editions).
  • Standard API Key: pay-as-you-go, connect with an existing platform API key.

  Either way you then pick the platform explicitly (China or International), so the UI language never decides your endpoint. See Authentication → Option 2: QwenCloud for details.

• Alibaba ModelStudio — opens a sub-menu:

  • Coding Plan: connect with an Alibaba Cloud Coding Plan API key. See Authentication for setup.
  • Token Plan: usage-based billing with a dedicated endpoint, aimed at teams and companies. See the Token Plan guide (intl) for setup instructions.
  • Standard API Key: connect with an existing API key from Alibaba Cloud ModelStudio (Beijing / intl). See the API setup guide (Beijing / intl) for details.

• Third-party Providers — choose a built-in provider (DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty, and more) and connect with an API key.

• Custom Provider — manually connect a local server, proxy, or unsupported provider.

Note

Qwen Code stores its configuration and customizations in .qwen directories: ~/.qwen/ for user-level settings (e.g. settings.json) and global custom commands, and <project>/.qwen/ for project-specific files such as custom commands and summaries.

Tip

To configure authentication, start Qwen Code and run /auth. Use /doctor to check your current configuration at any time. See the Authentication page for details.

Step 3: Start your first session

Open your terminal in any project directory and start Qwen Code:

# optional
cd /path/to/your/project
# start qwen
qwen

You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type /help for available commands.

Chat with Qwen Code

Ask your first question

Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:

explain the folder structure

You can also ask Qwen Code about its own capabilities:

what can Qwen Code do?

Note

Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.

Make your first code change

Now let's make Qwen Code do some actual coding. Try a simple task:

add a hello world function to the main file

Qwen Code will:

1. Find the appropriate file
2. Show you the proposed changes
3. Ask for your approval
4. Make the edit

Note

Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.

Use Git with Qwen Code

Qwen Code makes Git operations conversational:

what files have I changed?

commit my changes with a descriptive message

You can also prompt for more complex Git operations:

create a new branch called feature/quickstart

show me the last 5 commits

help me resolve merge conflicts

Fix a bug or add a feature

Qwen Code is proficient at debugging and feature implementation.

Describe what you want in natural language:

add input validation to the user registration form

Or fix existing issues:

there's a bug where users can submit empty forms - fix it

Qwen Code will:

• Locate the relevant code
• Understand the context
• Implement a solution
• Run tests if available

Test out other common workflows

There are a number of ways to work with Qwen Code:

Refactor code

refactor the authentication module to use async/await instead of callbacks

Write tests

write unit tests for the calculator functions

Update documentation

update the README with installation instructions

Code review

review my changes and suggest improvements

Tip

Remember: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.

Essential commands

Here are the most important commands for daily use:

Command	What it does	Example
qwen	start Qwen Code	qwen
/auth	Change authentication method (in session)	/auth
/doctor	Check current authentication and environment	/doctor
/help	Display help information for available commands	/help or /?
/compress	Replace chat history with summary to save Tokens	/compress
/clear	Clear conversation history and free up context	/clear (aliases: reset, new)
/theme	Change Qwen Code visual theme	/theme
/language	View or change language settings	/language
→ ui [language]	Set UI interface language	/language ui zh-CN
→ output [language]	Set LLM output language	/language output Chinese
/quit	Exit Qwen Code immediately	/quit or /exit

See the CLI reference for a complete list of commands.

Pro tips for beginners

Be specific with your requests

• Instead of: "fix the bug"
• Try: "fix the login bug where users see a blank screen after entering wrong credentials"

Use step-by-step instructions

• Break complex tasks into steps:

1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information

Let Qwen Code explore first

• Before making changes, let Qwen Code understand your code:

analyze the database schema

build a dashboard showing products that are most frequently returned by our UK customers

Save time with shortcuts

• Press ? to see all available keyboard shortcuts
• Use Tab for command completion
• Press ↑ for command history
• Type / to see all slash commands

Getting help

• In Qwen Code: Type /help or ask "how do I..."
• Documentation: You're here! Browse other guides
• Community: Join our GitHub Discussion for tips and support