Hướng dẫn Pyright: Kiểm tra kiểu tĩnh nhanh cho mã Python

Type hint giúp mã Python dễ hiểu và dễ bảo trì hơn. Nhưng vấn đề là: chỉ riêng hint thì không phát hiện được lỗi. Bạn cần một bộ kiểm tra kiểu để xác minh mã của mình thực sự tuân theo các kiểu đã khai báo.

Tôi đã dùng cả Mypy và Pyright trong môi trường production. Lợi thế về tốc độ của Pyright thể hiện rõ nhất khi phát triển. Lỗi kiểu xuất hiện ngay khi bạn gõ thay vì sau khi lưu. Với các codebase lớn, vòng phản hồi nhanh hơn này tạo ra khác biệt thực sự.

Hướng dẫn này bao quát mọi thứ bạn cần để dùng Pyright hiệu quả. Tôi sẽ chỉ bạn cách cài đặt, cấu hình cho dự án của bạn, và tích hợp với VS Code. Tôi cũng sẽ phân tích điểm khác nhau giữa Pyright và Mypy.

Pyright là gì?

Pyright là bộ kiểm tra kiểu tĩnh cho Python do Microsoft phát triển. Nó đọc mã của bạn, phân tích chú thích kiểu và báo lỗi khi kiểu không khớp. Khác với kiểm tra lúc chạy chỉ bắt lỗi khi mã thực thi, phân tích tĩnh bắt lỗi trước khi bạn chạy bất cứ thứ gì.

Trong khi hầu hết công cụ Python được viết bằng Python, Pyright được viết bằng TypeScript và chạy trên Node.js. Có vẻ lạ cho một công cụ Python, đúng không? Nhưng đó là lý do Pyright rất nhanh. Engine JavaScript V8 chạy nhanh hơn nhiều so với CPython.

Bạn sẽ gặp Pyright theo hai cách. Bạn có thể chạy nó như một công cụ dòng lệnh trong pipeline CI/CD để bắt lỗi kiểu trước khi merge. Hoặc có thể bạn đã dùng nó mà không biết. Nó là động cơ phía sau Pylance, tiện ích mở rộng Python của Microsoft cho VS Code. Những gạch đỏ dưới lỗi kiểu? Đó là Pyright đang chạy nền.

Công cụ này đi kèm type stub cho thư viện chuẩn Python và các gói phổ biến. Bạn không cần cài gì thêm để kiểm tra mã dùng os, json hoặc typing. Với gói bên thứ ba, Pyright dùng stub do cộng đồng duy trì từ typeshed hoặc stub riêng của gói mà bạn cài riêng.

Cách cài đặt Pyright

Giờ hãy chạy Pyright trên hệ thống của bạn. Bạn có hai lựa chọn cài đặt: npm (cách gốc) hoặc pip (wrapper Python).

Cài đặt Pyright bằng npm

Khuyến nghị dùng npm vì Pyright chạy trên Node.js. Bạn cần Node.js phiên bản 14.0.0 trở lên.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyrightĐược hỗ trợ bởi

Tôi dùng cài đặt toàn cục cho các lần kiểm tra nhanh và cài đặt cục bộ cho dự án nơi tôi muốn cố định phiên bản. Cách dùng npx hữu ích cho các lần chạy đơn lẻ mà không thêm vào gói toàn cục.

Cài đặt Pyright qua Python wrapper

Nếu nhóm của bạn chỉ làm việc trong Python và không muốn Node.js trong toolchain, có một wrapper trên PyPI:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]Được hỗ trợ bởi

Wrapper sẽ kiểm tra Node.js trên hệ thống của bạn. Nếu thiếu, wrapper sẽ tự động tải về bản độc lập. Phần mở rộng [nodejs] dùng phương thức tải đáng tin cậy hơn so với mặc định.

Hãy nhớ các đánh đổi. Lần chạy đầu tiên sẽ lâu hơn do tải phụ thuộc. Môi trường CI có hạn chế mạng có thể bị lỗi. Và phiên bản trên PyPI đôi khi chậm hơn bản phát hành npm vài ngày.

Với hầu hết nhóm Python, wrapper hoạt động ổn. Nhưng nếu gặp sự cố, hãy quay về cài đặt bằng npm. Cách này ổn định hơn.

Chạy Pyright trên một dự án Python

Sau khi cài đặt, chạy Pyright rất đơn giản. Điều hướng đến thư mục dự án và chạy:

pyrightĐược hỗ trợ bởi

Vậy là xong. Pyright quét các tệp Python, phân tích và báo mọi lỗi kiểu mà nó tìm thấy. Không cần thiết lập phức tạp.

Pyright kiểm tra những gì theo mặc định

Pyright tìm những gì? Không cần cấu hình, nó thực hiện một số kiểm tra. Nó xác thực chú thích kiểu khớp với cách sử dụng thực tế. Nó bắt biến chưa được định nghĩa và mã không thể đạt tới. Nó xác minh import hợp lệ. Nó gắn cờ các sai lệch kiểu rõ ràng như truyền chuỗi nơi cần số nguyên.

Dưới đây là ví dụ đầu ra từ một dự án có lỗi:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informationsĐược hỗ trợ bởi

Mỗi lỗi hiển thị đường dẫn tệp, số dòng, cột và mô tả. Tên quy tắc trong ngoặc (như reportArgumentType) cho biết chính xác kiểm tra nào kích hoạt lỗi. Điều này quan trọng khi bạn muốn bỏ qua các quy tắc cụ thể. Chúng ta sẽ nói ngay sau đây.

Hiểu mã thoát (exit code)

Pyright trả về các mã thoát khác nhau tùy theo kết quả:

Trong pipeline CI, bạn thường muốn build thất bại với mã thoát 1. Mã 2–4 cho thấy có sự cố với chính công cụ, không phải mã của bạn.

Cấu hình Pyright

Dù Pyright chạy tốt ngay từ đầu, dự án thực tế cần tùy chỉnh. Bạn sẽ muốn chỉ định tệp nào cần kiểm tra, phiên bản Python mục tiêu, và mức độ nghiêm ngặt của phân tích. Hãy xem các tùy chọn cấu hình chính.

Chế độ kiểm tra kiểu

Pyright cung cấp bốn mức nghiêm ngặt. Chế độ bạn chọn quyết định có bao nhiêu quy tắc được bật.

Nên chọn chế độ nào? Với dự án mới, hãy bắt đầu với chế độ standard. Nó bắt lỗi thực tế mà không dồn dập. Làm việc với mã kế thừa? Chế độ basic phù hợp hơn khi bạn áp dụng typing dần dần. Dành chế độ strict cho thư viện và hạ tầng quan trọng nơi bạn cần an toàn tối đa.

Lưu ý: bước nhảy từ standard sang strict là rất lớn. Strict bật khoảng 30 quy tắc bổ sung, bao gồm yêu cầu chú thích kiểu cho mọi tham số hàm và giá trị trả về. Hãy kỳ vọng số lỗi được báo tăng gấp 10 lần khi chuyển đổi. Tôi đã học điều này theo cách khó khăn.

Chế độ strict yêu cầu chú thích kiểu đầy đủ. Ảnh: Tác giả

Tệp cấu hình

Pyright đọc cấu hình từ pyrightconfig.json hoặc pyproject.toml. Nếu cả hai cùng tồn tại, pyrightconfig.json có ưu tiên cao hơn.

Đây là pyrightconfig.json tối thiểu:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}Được hỗ trợ bởi

Tương đương trong pyproject.toml:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"Được hỗ trợ bởi

Tệp cấu hình kiểm soát hành vi của Pyright. Ảnh: Tác giả.

Một chi tiết quan trọng khiến nhiều người vấp phải: nếu bạn tự định nghĩa exclude, nó thay thế hoàn toàn mặc định. Luôn thêm node_modules, __pycache__ và môi trường ảo của bạn vào mẫu exclude tùy chỉnh. Nếu không, Pyright sẽ cố phân tích phụ thuộc của bạn, gây chậm nghiêm trọng. Tin tôi đi, bạn không muốn chờ 10 phút cho một lần kiểm tra kiểu.

Cấu hình môi trường ảo

Pyright tìm các gói đã cài ở đâu? Bạn cần cho nó biết nơi cần tìm. Cấu hình bằng venvPath và venv:

{
  "venvPath": ".",
  "venv": ".venv"
}Được hỗ trợ bởi

Điều này cho Pyright biết tìm gói ở ./.venv. Nếu bạn dùng vị trí môi trường ảo khác, hãy điều chỉnh tương ứng. Nếu không có cấu hình này, Pyright không thể tìm phụ thuộc đã cài và sẽ báo lỗi thiếu import cho mọi thứ.

Bỏ qua chẩn đoán

Đôi khi Pyright đúng về mặt kỹ thuật nhưng bạn vẫn cần im lặng một số lỗi. Có thể bạn làm việc với mã kế thừa, hoặc bạn biết rõ hơn bộ kiểm tra kiểu trong một trường hợp cụ thể. Bạn có thể bỏ qua lỗi ở ba mức.

Bỏ qua ở mức cấu hình

Tắt quy tắc toàn cục:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}Được hỗ trợ bởi

Bỏ qua ở mức tệp

Thêm comment ở đầu tệp:

# pyright: basic
# pyright: reportPrivateUsage=falseĐược hỗ trợ bởi

Bỏ qua ở mức dòng

Bỏ qua một dòng duy nhất:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]Được hỗ trợ bởi

Cú pháp quy tắc cụ thể ([reportAssignmentType]) hữu ích khi bạn muốn im lặng một kiểm tra mà không tắt các kiểm tra khác trên cùng dòng.

Sau khi cấu hình xong, hãy xem Pyright tích hợp với môi trường phát triển của bạn như thế nào.

Pyright trong VS Code và IDE

Nếu bạn giống đa số lập trình viên Python, bạn sẽ trải nghiệm Pyright qua Pylance hơn là dòng lệnh. Hiểu mối quan hệ này giúp bạn cấu hình trình soạn thảo đúng cách và tránh lỗi thường gặp.

Pyright vs. Pylance

Pylance là tiện ích VS Code của Microsoft gói kèm động cơ kiểm tra kiểu của Pyright. Khi bạn cài Pylance, bạn có Pyright tự động. Nhưng Pylance thêm các tính năng không có trong Pyright mã nguồn mở:

• Tô sáng ngữ nghĩa: tô màu biến theo kiểu
• Tự động import nâng cao: gợi ý import thông minh hơn
• Điều hướng mã: "Tìm tất cả tham chiếu" trên toàn workspace

Những tính năng này là mã nguồn đóng và chỉ có trên VS Code. Nếu bạn dùng Neovim, Emacs, hoặc trình soạn khác, bạn có chức năng cốt lõi của Pyright nhưng không có các tính năng bổ sung này.

Pylance đánh dấu lỗi kiểu trong trình soạn thảo. Ảnh: Tác giả.

Cài đặt VS Code thiết yếu

Cấu hình Pylance qua phần cài đặt của VS Code:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}Được hỗ trợ bởi

Thiết lập diagnosticMode ảnh hưởng đến hiệu năng. "openFilesOnly" chỉ phân tích các tệp bạn đang mở. "workspace" phân tích mọi thứ nhưng dùng nhiều bộ nhớ và CPU hơn.

Những lỗi cấu hình thường gặp

Trình thông dịch được chọn rất quan trọng. Pylance dùng trình thông dịch Python bạn chọn để tìm các gói đã cài. Nếu bỗng dưng xuất hiện lỗi với các gói bạn biết là đã cài, hãy kiểm tra xem trình thông dịch đúng đã được chọn trong thanh trạng thái VS Code chưa.

Chọn trình thông dịch ảnh hưởng đến đường dẫn phát hiện gói. Ảnh: Tác giả.

Mặc định của CLI và Pylance khác nhau. Pylance mặc định typeCheckingMode là "off" trong khi CLI mặc định là "standard". Pylance cũng tự động thêm src vào đường dẫn tìm kiếm; CLI thì không. Để hành vi nhất quán giữa trình soạn thảo và CI, hãy đặt rõ mọi tùy chọn trong pyproject.toml.

Hiện tượng "mã bị làm mờ". Pylance làm mờ mã không thể đạt tới dựa trên phân tích kiểu. Nếu mã bị làm mờ ngoài ý muốn, hãy kiểm tra hàm được gọi ngay trước đó. Một hàm được gán kiểu trả về NoReturn khiến mọi thứ phía sau bị coi là không thể đạt tới.

Pyright vs. Mypy: Khi nào dùng mỗi công cụ

Bạn có thể tự hỏi: nên dùng Pyright hay tiếp tục với Mypy? Cả hai đều sẵn sàng cho production, và lựa chọn phụ thuộc vào quy trình làm việc và yêu cầu của bạn. Tôi sẽ phân tích những khác biệt chính.

Tốc độ và độ phản hồi

Pyright nhanh hơn khoảng 3–5 lần so với Mypy khi quét toàn dự án và gần như tức thời cho kiểm tra gia tăng. Điều này quan trọng nhất trong phát triển khi bạn muốn phản hồi ngay.

Mypy có chế độ daemon (dmypy) cải thiện hiệu năng, nhưng vẫn chậm hơn và đôi khi gặp vấn đề cache cần khởi động lại.

Khác biệt trong suy luận kiểu

Điểm thú vị nằm ở đây. Hai công cụ suy luận kiểu khác nhau. Xem đoạn mã sau:

coordinates = (10, 20)Được hỗ trợ bởi

Pyright suy luận tuple[Literal[10], Literal[20]], giữ nguyên giá trị vì tuple là bất biến. Mypy suy luận tuple[int, int], mở rộng thành kiểu tổng quát.

Cách của Pyright bắt nhiều lỗi hơn nhưng đôi khi gây vướng víu khi hàm mong đợi kiểu tổng quát. Điều này hiếm khi quan trọng trong thực tế vì Literal[10] là một kiểu con hợp lệ của int.

Phân tích mã chưa chú thích

Đây là khác biệt thực tế lớn nhất, và là yếu tố thay đổi cuộc chơi cho codebase kế thừa. Mypy bỏ qua các hàm chưa chú thích theo mặc định. Pyright vẫn phân tích chúng, bắt các lỗi hiển nhiên ngay cả khi không có type hint.

Với codebase cũ ít chú thích, Pyright hoạt động như một linter mạnh mẽ, bắt biến chưa định nghĩa và lời gọi phương thức bất khả thi. Mypy coi các hàm đó là "dynamic" và bỏ qua.

Hỗ trợ plugin

Mypy hỗ trợ plugin cho các framework như Django và SQLAlchemy. Các plugin này hiểu ORM magic và cung cấp kiểu chính xác cho thuộc tính được tạo động.

Pyright không có hệ thống plugin. Nó hoàn toàn dựa vào type stub. Năm 2026, hầu hết thư viện lớn đều có stub chất lượng cao, nên việc này ít quan trọng hơn trước. Nhưng nếu bạn dùng framework có metaprogramming nặng, hãy kiểm tra xem có stub tốt hay không trước khi cam kết với Pyright.

Hãy dùng Pylance (Pyright) trong phát triển để có phản hồi tức thời, và cân nhắc chạy cả Pyright lẫn Mypy trong CI nếu dự án dùng plugin framework.

Vấn đề thường gặp khi dùng Pyright

Khi Pyright báo lỗi ngoài dự kiến, nguyên nhân thường là một trong các vấn đề sau.

Thiếu type stub

Bạn từng thấy lỗi này? Pyright phàn nàn khi không tìm được thông tin kiểu cho một gói:

Import "requests" could not be resolved (reportMissingImports)Được hỗ trợ bởi

Thiếu stub sẽ kích hoạt cảnh báo import. Ảnh: Tác giả.

Đầu tiên, kiểm tra gói đã được cài trong môi trường ảo của bạn chưa và Pyright có biết nơi để tìm (dùng thiết lập venvPath và venv đã nêu).

Nếu gói đã cài nhưng thiếu thông tin kiểu, hãy cài stub của cộng đồng:

pip install types-requests types-PyYAML types-redisĐược hỗ trợ bởi

Với các gói không có stub, bạn có hai lựa chọn. Bạn có thể tắt cảnh báo bằng "reportMissingTypeStubs": "none" trong cấu hình. Hoặc tự tạo stub nháp:

pyright --createstub some_packageĐược hỗ trợ bởi

Lệnh này tạo tệp khung .pyi để bạn điền các phương thức mình thực sự dùng.

Lỗi pre-commit hook

Pyright chạy ổn cục bộ nhưng lỗi trong pre-commit? Nguyên nhân thường là cô lập môi trường. Pre-commit chạy hook trong môi trường tách biệt không thấy các gói đã cài của dự án bạn.

Khắc phục bằng cách trỏ hook đến môi trường ảo của bạn:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]Được hỗ trợ bởi

Lỗi bất ngờ ở chế độ strict

Bật chế độ strict và bỗng thấy hàng nghìn lỗi? Đừng hoảng. Điều này là bình thường. Strict yêu cầu chú thích kiểu đầy đủ. Hãy bắt đầu với basic hoặc standard, thêm chú thích dần, và chỉ bật strict trên các module đã được chú thích đầy đủ.

Dùng comment theo tệp để giữ mã kế thừa ở chế độ dễ dãi:

# pyright: basicĐược hỗ trợ bởi

Cách này cho phép bạn áp dụng kiểm tra nghiêm ngặt cho mã mới trong khi dần di chuyển mã cũ.

Ngoài khắc phục sự cố, dưới đây là vài chiến lược giúp trải nghiệm Pyright mượt mà ngay từ đầu.

Thực hành tốt khi dùng Pyright

Sau khi làm việc với Pyright trên nhiều dự án, tôi rút ra vài điều giúp việc áp dụng trơn tru hơn. Áp dụng các thực hành và hướng dẫn viết mã tốt này đảm bảo kiểm tra kiểu là công cụ hỗ trợ, không phải cản trở.

Bắt đầu với chế độ standard. Như đã đề cập, nó bắt lỗi thực tế mà không yêu cầu chú thích đầy đủ. Bạn luôn có thể siết chặt quy tắc sau.

Cố định phiên bản Pyright. Pyright phát hành thường xuyên, và phiên bản mới đôi khi gắn cờ mã trước đó từng pass. Trong CI, một lệnh pip install pyright không cố định có thể khiến build sáng thứ Hai hỏng do bản phát hành cuối tuần. Tôi đã từng. Không vui chút nào.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"Được hỗ trợ bởi

# In requirements-dev.txt
pyright==1.1.408Được hỗ trợ bởi

Sửa lỗi dần dần. Đừng cố loại bỏ 10.000 lỗi cùng lúc. Dùng mảng strict để áp dụng kiểm tra nghiêm ngặt chỉ cho các thư mục cụ thể:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}Được hỗ trợ bởi

Dùng tệp cấu hình ngay từ sớm. Ngay cả với dự án nhỏ, cấu hình rõ ràng giúp tránh bất ngờ. Dành năm phút để ghi lại phiên bản Python, đường dẫn môi trường ảo và mức nghiêm ngặt đã chọn. Bạn sẽ cảm ơn chính mình sau này.

Đừng nhắm đến sự hoàn hảo ngay lập tức. Dùng # pyright: ignore một cách rộng rãi lúc đầu. Điều này đánh dấu nợ kỹ thuật một cách rõ ràng để bạn dọn dẹp theo thời gian thay vì chặn tiến độ. Hoàn hảo là kẻ thù của tốt, đặc biệt khi áp dụng công cụ mới.