Guide · Open source

How to use ItChat: install, log in and build a WeChat bot

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

ItChat is an open-source Python library that lets a program log in to a personal WeChat account and send, receive and reply to messages. This guide shows you how to install it, log in, send a message, write a simple auto-reply bot and download files. It is aimed at Python users who are comfortable running scripts and scanning a login QR code.

ItChatlittlecodersh/ItChat · ★ 26.5k · MIT Install options & downloads

Quick start

1Install the package. Run pip install itchat in your terminal to install ItChat from PyPI.
2Create a script and log in. Import itchat and call itchat.auto_login(). Scan the QR code with your WeChat app to sign in.
3Register a message handler. Use the msg_register decorator on a function, and return the text you want sent as a reply.
4Keep the bot running. Call itchat.run() at the end of the script so the program keeps receiving messages.
5Test with the file transfer assistant. Send a message to filehelper first, since the README recommends it when other targets fail.

Install ItChat from PyPI

The README gives one install command: install ItChat from PyPI with pip. Run it in the terminal or command prompt where your Python is installed.

The README's badges mention Python 2.7 and 3.5, but the text does not state which Python version is current for the latest release. Check the project documentation before you start.

pip install itchat

Calling auto_login() starts the login flow. The README's first example sends a message to the file transfer assistant, which is the account named filehelper. You scan the login QR code to sign in.

The README says a simple bot can be written in under thirty lines. This first example only sends one message and does not keep running.

Use toUserName='filehelper' to send to the file transfer assistant.
Some accounts cannot send messages to themselves, so the README recommends filehelper for testing.

import itchat

itchat.auto_login()

itchat.send('Hello, filehelper', toUserName='filehelper')

Write a simple auto-reply bot

The msg_register decorator attaches a function to a message type. The function's return value is sent back as the reply. This example replies to text messages sent to your own account.

itchat.run() keeps the program running so it can receive messages. Stop the script to stop the bot.

msg_register(itchat.content.TEXT) matches plain text messages.
The value you return from the function becomes the reply text.

import itchat

@itchat.msg_register(itchat.content.TEXT)
def text_reply(msg):
    return msg.text

itchat.auto_login()
itchat.run()

Handle different message types and files

You can register one handler for several message types by passing a list. The README's example covers text, map, card, note and sharing messages in one handler, and picture, recording, attachment and video messages in another.

Downloads use msg.download(). Pass a file name to save the file locally. If you call it with no argument, the method returns the binary data so you can process it yourself.

The README also shows how to handle friend requests with msg.user.verify() and how to reply in group chats only when the bot is mentioned with msg.isAt.

Use isGroupChat=True on msg_register to target group chats.
msg.fileName holds the file name for sent files and pictures.

from itchat.content import *

@itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO])
def download_files(msg):
    msg.download(msg.fileName)
    typeSymbol = {
        PICTURE: 'img',
        VIDEO: 'vid', }.get(msg.type, 'fil')
    return '@%s@%s' % (typeSymbol, msg.fileName)

Search for friends and read their details

The search_friends method finds users. With no arguments it returns your own user information. You can search by UserName, or by a name that matches remark name, WeChat ID or nickname.

The README notes that group chat and public account lookups are covered in the full documentation.

userName searches for one specific UserName.
name matches any of remark name, WeChat ID or nickname.
wechatAccount and name can be combined in one call.

itchat.search_friends()
itchat.search_friends(name='littlecodersh')
itchat.search_friends(name='LittleCoder机器人', wechatAccount='littlecodersh')

By default the login QR code is shown as an image. The README shows enableCmdQR to draw it in the command line. Set it to a negative value on light backgrounds, or to a multiple if characters are the wrong width on your system.

hotReload=True saves the login state so that, for a limited time, restarting the program does not require scanning the code again. The README says the time window is limited but does not give its length.

enableCmdQR=2 is the README's example for systems where block characters are one character wide.
enableCmdQR=-1 is for light console backgrounds.

itchat.auto_login(enableCmdQR=True)
itchat.auto_login(hotReload=True)

What people use it for

Sending a message to the filehelper account from a Python script.
Replying automatically to text messages sent to your own account.
Downloading pictures, videos or attachments that arrive in chat and saving them locally.
Searching your friend list by name or WeChat ID from a script.
Building a small bot that responds to @-mentions in group chats.

Frequently asked questions

Is ItChat free to use?

ItChat is released under the MIT licence, as stated in the project's README. The MIT licence allows use, modification and redistribution, and you can read the full terms in the repository.

What do I need to run ItChat?

You need Python and a personal WeChat account that you can sign in to by scanning a QR code. The README gives pip install itchat as the install method and does not list other requirements in the text provided.

Is ItChat an official WeChat API?

No. The README describes it as an interface for personal WeChat accounts, not the official public-account API. The README points to a separate project, itchatmp, for the official public account interface.

Why did my message fail to send?

The README says some accounts cannot send messages to themselves. It recommends sending to filehelper instead, which is the file transfer assistant account.

What are the alternatives to ItChat?

The README lists wxpy, wechaty, wxBot, Mojo-Weixin, vbot, itchat4j and jeeves as similar projects. wxpy is described as an API wrapper with plugins, wechaty as a Node.js framework, and Mojo-Weixin as a Perl client framework.

Will my ItChat bot keep working long term?

The README does not promise long-term stability. It warns that WeChat changes can break unofficial clients, so check the repository's recent activity before relying on it for anything important.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ItChat suits Python developers, hobbyists and experimenters who want to script a personal WeChat account or build a simple auto-reply bot. It is not a good fit for business teams that need an official integration, or for anyone who needs guaranteed long-term stability, since it depends on an unofficial interface.

Install options & downloads