Cài đặt

Thế hệ 5 phát hành trên kho gói của vnstocks.com, không phải trên PyPI. Lệnh cài phải có --extra-index-url: chạy pip install vnstock không kèm chỉ mục thì pip lấy bản 4.x từ PyPI.

Yêu cầu

Cài vào đâu

Vnstock cài vào một môi trường ảo cố định, ở cùng một chỗ trên mọi máy:

Thế hệ 5 chỉ phụ thuộc pandas nên cài ở đâu cũng chạy. Giữ một chỗ cố định là để khi gặp vướng, bạn, nhóm hỗ trợ và trợ lý AI đều biết ngay Python đầy đủ cho vnstock nằm ở đâu, không phải dò từng bản Python trên máy. Muốn cài chỗ khác (môi trường riêng của dự án, conda, uv) thì cứ cài, chỉ cần nhớ đó là chỗ của mình.

Trước khi cài: máy đã có bản cũ chưa?

Trình cài của bản 4.x cũng dùng ~/.venv. Nếu thư mục này đã có, xem bên trong trước khi cài (lệnh chỉ đọc, không đổi gì):

~/.venv/bin/python -m pip show vnstock vnstock_data vnai          # macOS, Linux

& "$HOME\.venv\Scripts\python.exe" -m pip show vnstock vnstock_data vnai   # Windows

Thấy vnstock 4.x, vnstock_data hay vnai thì đừng cài thế hệ 5 vào đó: hai thế hệ cùng tên gói vnstock, bản sau đè bản trước, và bản cũ không trở lại như trước được. Cài thế hệ 5 vào ~/.venv5x (Windows $HOME\.venv5x) bằng đúng các lệnh dưới đây, thay .venv bằng .venv5x. Bản cũ vẫn chạy trong ~/.venv; khi đã chuyển hết mã sang thế hệ 5 theo hướng dẫn chuyển đổi thì mới dọn nó.

macOS

1. Cần Python 3.10 trở lên: python3 --version. Bản python3 đi kèm công cụ dòng lệnh Xcode là 3.9, không đủ; cài từ python.org hoặc brew install python.

2. Tạo môi trường (bỏ qua nếu đã có) và cài:

   Shell

   python3 -m venv ~/.venv
   ~/.venv/bin/python -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Linux

1. python3 --version từ 3.10. Debian và Ubuntu cần gói venv của bản phân phối; nếu lệnh tạo môi trường báo ensurepip is not available, chạy sudo apt install python3-venv rồi tạo lại.

2. Tạo môi trường và cài:

   Shell

   python3 -m venv ~/.venv
   ~/.venv/bin/python -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Đừng cài vào Python hệ thống bằng sudo pip hay --break-system-packages.

Windows

1. Cài Python 3.10 trở lên từ python.org, không dùng bản Microsoft Store. Kiểm tra trong PowerShell: py --version (máy có nhiều bản thì py -0p liệt kê, chọn một bản bằng py -3.12).

2. Tạo môi trường và cài, trong PowerShell:

   POWERSHELL

   py -m venv "$HOME\.venv"
   & "$HOME\.venv\Scripts\python.exe" -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Dùng môi trường hằng ngày

Gọi thẳng Python và lệnh vnstock của môi trường thì không cần kích hoạt gì:

~/.venv/bin/vnstock status                    # macOS, Linux

& "$HOME\.venv\Scripts\vnstock.exe" status   # Windows

Muốn gõ python, vnstock trực tiếp thì kích hoạt môi trường trong terminal đó: source ~/.venv/bin/activate (macOS, Linux) hoặc & "$HOME\.venv\Scripts\Activate.ps1" (Windows; nếu PowerShell chặn script, chạy một lần Set-ExecutionPolicy -Scope CurrentUser RemoteSigned).

Trong VS Code, Cursor hay Antigravity, chọn trình thông dịch (Python: Select Interpreter) là ~/.venv/bin/python (Windows %USERPROFILE%\.venv\Scripts\python.exe). Dùng Jupyter trên máy thì đăng ký môi trường thành một kernel, rồi chọn kernel Python (Vnstock) trong notebook:

~/.venv/bin/python -m pip install ipykernel
~/.venv/bin/python -m ipykernel install --user --name=vnstock-venv --display-name "Python (Vnstock)"

Cờ --extra-index-url trong lệnh cài là bắt buộc: thế hệ 5 nằm trên kho thư viện của vnstocks.com. Lệnh pip install vnstock trơn, không kèm kho này, vẫn lấy bản 4.x từ PyPI.

Kiểm tra (macOS, Linux; trên Windows thay bằng đường dẫn $HOME\.venv\Scripts\ như trên):

~/.venv/bin/python -c "import vnstock; print(vnstock.__version__)"   # 5.x.x
~/.venv/bin/vnstock version                                           # bản đang cài và bản mới nhất

Không tìm thấy lệnh vnstock

Cài xong mà terminal báo vnstock không phải là lệnh (is not recognized, command not found) thì thư viện không hỏng: lệnh vnstock nằm trong môi trường, và terminal chưa kích hoạt môi trường đó. Gọi bằng đường dẫn đầy đủ (~/.venv/bin/vnstock, Windows $HOME\.venv\Scripts\vnstock.exe) hoặc kích hoạt như mục trên. Nếu bạn cài vào một Python khác, chạy cùng lệnh qua Python đó:

python -c "from vnstock.cli import main; raise SystemExit(main())" status

Thay status bằng register, install --list, install, doctor. Để sửa hẳn, kích hoạt một môi trường ảo (thư mục lệnh của nó tự vào PATH), hoặc thêm thư mục in ra bởi lệnh dưới đây vào PATH của tài khoản rồi mở terminal mới:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

Trên Windows, Python cài từ Microsoft Store giấu thư mục này trong một đường dẫn riêng; nên cài Python từ python.org.

Google Colab

Thêm ! trước lệnh:

!pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Colab có thể đã cài sẵn bản khác của vnstock. Sau khi cài, chọn Runtime → Restart session rồi mới import vnstock, để notebook nạp đúng bản vừa cài.

Trên GitHub Codespaces cũng vậy: chạy lệnh pip (không có !) trong terminal của Codespace, không tạo môi trường ảo.

Đăng nhập

Không có khoá API, thư viện chạy ở cấp Khách với một phần hàm và giới hạn chặt hơn. Có khoá thì đăng nhập một lần trên mỗi máy:

vnstock register        # hỏi khoá, gõ không hiện lên màn hình
vnstock status          # xem lại cấp, hạn dùng, thiết bị

Trong notebook:

import os
import vnstock

vnstock.login(os.environ["VNSTOCK_API_KEY"])
vnstock.status()

Lấy khoá ở trang tài khoản. Đừng gõ khoá thẳng vào mã hay dán vào khung chat của trợ lý AI; đặt nó trong biến môi trường VNSTOCK_API_KEY hoặc tệp .env của dự án. Các cách đăng nhập khác, kể cả trong script và CI, ở trang Đăng nhập và dòng lệnh. Hàm nào mở ở cấp nào ở trang Cấp tài khoản và giới hạn.

Thư viện bổ sung

Thế hệ 5 có bốn thư viện. vnstock là thư viện chính; ba thư viện còn lại mở theo cấp tài khoản:

Các thư viện cấp của khoá bạn được dùng cài bằng lệnh của vnstock, vào đúng trình Python đang chạy lệnh:

vnstock install --list     # xem trước, không cài gì
vnstock install            # cài tất cả
vnstock install -U         # nâng các thư viện đã cài lên bản mới nhất

vnstock install dùng uv nếu bạn đang ở trong môi trường ảo có uv, không thì dùng pip; ép một trình cài bằng --tool pip hoặc --tool uv. Một thư viện cài xong mà không import được thì lệnh in lý do.

Nâng cấp

Chạy lại lệnh cài, giữ -U:

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

vnstock version cho biết có bản mới hơn trên kho hay không.

Hạn dùng của bản cài

Mỗi bản phát hành dùng được 365 ngày, tính từ ngày bản đó được đưa lên kho gói. Thư viện báo trước 30 ngày.

Trong thời gian báo trước, lần gọi dữ liệu đầu tiên của mỗi tiến trình in một cảnh báo FutureWarning kèm ngày hết hạn và lệnh nâng cấp. Quá hạn, hàm dữ liệu từ chối chạy với mã lỗi VNSTOCK_RELEASE_EXPIRED, kèm lệnh nâng cấp. vnstock status cho biết hạn của bản đang cài.

Cứ nâng cấp đều là không gặp hạn.

Gỡ cài đặt

pip uninstall vnstock
vnstock logout    # chạy trước khi gỡ nếu muốn xoá khoá và quyền đã lưu trên máy

Thư mục trạng thái của thư viện (khoá đã mã hoá, quyền, cài đặt ngôn ngữ) xem bằng vnstock env.