Typer 0.29.0, phát hành ngày 9/11/2026, đưa Pydantic vào validate tham số dòng lệnh. Đây là bước di chuyển lớn đầu tiên của Typer khỏi Click sang Pydantic, kèm vài thay đổi tương thích mà người viết CLI cần biết trước khi nâng cấp.

Typer vốn nổi tiếng nhờ biến type hint Python thành giao diện dòng lệnh gần như không cần code thừa. Việc chuyển sang Pydantic giúp validate tham số chặt chẽ và nhất quán hơn với FastAPI — nhưng một số hành vi cũ sẽ không còn hoạt động như trước.

Pydantic validate tham số CLI: thay đổi lớn nhất

Từ 0.29.0, Typer dùng Pydantic để validate tham số dòng lệnh thay vì dựa hoàn toàn vào Click. Đây là quá trình di chuyển từng bước, ưu tiên giữ tương thích với ứng dụng hiện có.

Lợi ích rõ nhất: cùng một “bộ não” validate với FastAPI và Pydantic v2, nên kiểu dữ liệu và thông báo lỗi nhất quán hơn giữa API và CLI trong cùng một dự án. Pydantic từ 2.5.3 trở lên trở thành dependency bắt buộc của Typer.

Thông báo lỗi, văn bản trợ giúp và output sử dụng đã thay đổi ít nhiều — test nào so khớp chuỗi output CLI cần chạy lại và cập nhật.

Những thay đổi tương thích cần kiểm tra trước khi nâng cấp

  • click_type đã bị loại khỏi typer.Option() và typer.Argument(). Kiểu tùy chỉnh mới sẽ đến qua Pydantic, linh hoạt hơn — nhưng code cũ dùng click_type sẽ lỗi ngay khi nâng cấp.
  • Giá trị mặc định được validate chặt hơn: tuple (None, None, None) trong tài liệu cũ nay không còn qua validate. Cách đúng là tuple[str, int, bool] | None với mặc định None, kiểm tra None trước khi unpack.
  • Ngày giờ mặc định nay parse theo quy tắc Pydantic: chấp nhận Unix timestamp, múi giờ và giây phân số.
  • Đối tượng tham số trong callback không còn lộ thuộc tính của Click như .type, .make_metavar() hay .type_cast_value(). Tích hợp tùy chỉnh nào dựa vào chúng cần cập nhật.
  • Bản 0.29.0 cũng vá lỗi hiển thị: ký tự điều khiển terminal trong thông báo lỗi validate của Pydantic nay được escape.

Bản 0.29.1: hỗ trợ Python 3.15

Hai ngày sau, bản 0.29.1 (11/11/2026) bổ sung hỗ trợ Python 3.15 và 3.15t, đồng thời làm rõ thêm các thay đổi tương thích. Nếu dùng Python 3.15, hãy nâng cấp thẳng lên 0.29.1 thay vì 0.29.0.

Điều này có ý nghĩa gì với bạn

Nếu CLI chỉ dùng các kiểu cơ bản như str, int, Path hay datetime và không động vào click_type hay thuộc tính nội bộ của Click, nâng cấp thường chỉ là pip install -U typer rồi chạy lại bộ test.

Nếu bạn xây CLI dùng chung với API FastAPI, đây là lúc hai phía dùng chung một chuẩn validate — ít bất ngờ hơn khi cùng một dữ liệu đi qua cả hai cửa.

Ngược lại, nếu dự án đang ổn định và bạn dùng click_type hoặc test so khớp output CLI theo từng ký tự, hãy pin phiên bản cũ rồi nâng cấp theo lịch của mình.

Bài viết liên quan

Câu hỏi thường gặp

Typer 0.29.0 có phá vỡ ứng dụng CLI hiện tại không?

Phần lớn không — nhóm phát triển di chuyển từng bước và ưu tiên tương thích. Nhưng code dùng click_type, default tuple (None, None, None), hoặc thuộc tính Click nội bộ trong callback sẽ cần sửa.

Có cần cài Pydantic riêng không?

Không. Pydantic từ 2.5.3 trở lên nay là dependency bắt buộc, pip sẽ tự cài khi bạn nâng cấp Typer.

Nên nâng cấp lên 0.29.0 hay 0.29.1?

Lên thẳng 0.29.1 — bản này giữ nguyên mọi thay đổi của 0.29.0 và thêm hỗ trợ Python 3.15 và 3.15t.

💬 Tin này ảnh hưởng tới dự án của bạn thế nào? Chia sẻ góc nhìn của bạn trong phần bình luận — mình đọc hết và sẽ tổng hợp những ý hay nhất.

Nguồn tham khảo