Gỡ lỗi & Câu hỏi thường gặp

Tổng quan

Quá trình cài đặt và sử dụng đôi khi gặp một số rào cản kỹ thuật phụ thuộc vào hệ điều hành hoặc môi trường lập trình. Tài liệu này giúp bạn tự chẩn đoán và khắc phục nhanh các sự cố phổ biến nhất.

1. Lỗi thiết lập cơ bản

1.1. Đã tài trợ nhưng vẫn báo bản Cộng đồng

Đây là bối rối phổ biến nhất của người tài trợ sau khi nhận gói tài trợ. Mặc dù tài khoản của bạn đã được kích hoạt thành công trên hệ thống, bạn vẫn thấy thông báo sử dụng bản Community, và giới hạn số kỳ hoặc tính năng chưa mở rộng sang gói tài trợ.

Nguyên nhân cốt lõi

Bạn đang chạy code dựa trên thư viện vnstock bản Cộng đồng. Thư viện vnstock không thể tự chuyển đổi sang tính năng của bản Mở rộng. Bản Mở rộng dùng một bộ thư viện độc lập, cần cài đặt riêng nhưng chuyển đổi code dễ dàng.

Cách xử lý

1. Cài đặt thư viện bản Mở rộng: Bộ thư viện dành cho người tài trợ là các thư viện riêng (như vnstock_data, vnstock_ta, vnstock_news, vnstock_pipeline), không thể cài đặt qua lệnh pip install vnstock_data thông thường. Bạn bắt buộc phải cài đặt thông qua trình cài đặt riêng tại trang Cài đặt bản Mở rộng.

2. Thay đổi câu lệnh Import trong code: Sau khi cài đặt thành công, hãy cập nhật lại toàn bộ mã nguồn của bạn để import từ thư viện mới:

   • Cách cũ (Bản Cộng đồng):
     Python

     from vnstock import Quote, Listing

   • Cách mới (Bản Mở rộng):
     Python

     from vnstock_data import Market, Reference

Khi bạn import từ vnstock_data, hệ thống sẽ tự động nhận diện API Key và áp dụng đúng cấp tài trợ của bạn: mở thêm các nhóm hàm và áp dụng quỹ hạn mức sử dụng chung của cấp đó. Phần trăm hạn mức còn lại của giờ, ngày, tháng xem ở trang tài khoản hoặc qua lệnh vnstock usage (hệ thống tính theo hạn mức sử dụng chung, không quản lý theo lượt request). Hạn mức là đơn vị kỹ thuật để giữ tải ở mức hợp lý với nguồn, không phải dữ liệu bán theo đơn vị.

1.2. Nâng cấp từ xác thực GitHub sang khoá API

Bước 1. Mở Terminal (macOS/Linux) hoặc Command Prompt / PowerShell (Windows).

Bước 2. Gỡ các thư viện Vnstock cũ:

pip uninstall vnstock vnai vnii vnstock_data vnstock_ta vnstock_news vnstock_pipeline vnstock_installer -y

Nếu máy có nhiều phiên bản Python, chỉ định phiên bản cụ thể, ví dụ python3.10 -m pip uninstall ....

Bước 3. Xoá thư mục cấu hình và môi trường ảo.

Trên macOS/Linux:

rm -rf ~/.vnstock ~/.venv

Trên Windows, hai cửa sổ dòng lệnh dùng lệnh khác nhau. Cách phân biệt: nếu dòng nhắc bắt đầu bằng PS C:\ thì đó là PowerShell, còn C:\ là Command Prompt.

Command Prompt:

rmdir /S /Q %USERPROFILE%\.vnstock %USERPROFILE%\.venv

PowerShell:

rm -r -force "$env:USERPROFILE\.vnstock", "$env:USERPROFILE\.venv"

Bước 4. Kiểm tra và chạy trình cài đặt. Phiên bản vnstock_installer phải từ 3.0.1 trở lên:

pip show vnstock_installer

Nếu chưa có hoặc bản cũ, cài lại. Giữ nguyên số phiên bản ở cuối lệnh — lý do ở mục 1.11 bên dưới:

pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.3

Rồi chạy trình cài đặt, chọn đúng phiên bản Python bạn muốn dùng:

python3.11 -m vnstock_installer

Hoặc gọi lệnh ngắn vnstock-installer. Cài trên máy chủ không có màn hình thì xem Dòng lệnh cho server và Colab.

1.3. Xác thực xong vẫn báo "Không tìm thấy thông tin người dùng hợp lệ" — bản cài giao diện

Bạn không cần cài lại từ đầu, chỉ cần tạo tệp cấu hình khoá API.

Bước 1. Lấy mã API của bạn tại trang tài khoản.

Bước 2. Tạo tệp api_key.json trong thư mục ~/.vnstock/ với nội dung:

{
  "api_key": "vnstock_code-cua-ban"
}

Bước 3. Chọn cách làm theo hệ điều hành. Thay YOUR_API_KEY bằng mã thật ở bước 1.

Trên macOS và Linux, mở Terminal và chạy:

mkdir -p ~/.vnstock
cat > ~/.vnstock/api_key.json << 'EOF'
{
  "api_key": "YOUR_API_KEY"
}
EOF
cat ~/.vnstock/api_key.json

Lệnh này tạo thư mục ~/.vnstock nếu chưa có, tạo tệp api_key.json, rồi in nội dung ra để bạn kiểm tra.

Trên Windows với Command Prompt:

cd %USERPROFILE%
if not exist .vnstock mkdir .vnstock
cd .vnstock
echo. > api_key.json

Sau đó mở api_key.json bằng Notepad, dán nội dung JSON ở bước 2 vào và lưu lại.

Trên Windows với PowerShell, chỉ cần một lệnh:

New-Item -Type Directory -Path "$env:USERPROFILE\.vnstock" -Force | Out-Null
@{"api_key"="YOUR_API_KEY"} | ConvertTo-Json | Out-File -FilePath "$env:USERPROFILE\.vnstock\api_key.json" -Encoding UTF8 -Force
Get-Content "$env:USERPROFILE\.vnstock\api_key.json"

Bước 4. Chạy lại code Python của bạn.

1.4. Xác thực xong vẫn báo "Không tìm thấy thông tin người dùng hợp lệ" — bản cài dòng lệnh

Dùng bản trình cài đặt dòng lệnh mới nhất để chạy lại. Bản vnstock_installer 3.0.1, phát hành ngày 20/11/2025, đã sửa lỗi này. Nếu vẫn chưa được, làm theo mục 1.5.

1.5. Tệp user.json vẫn không được tạo

Bước 1. Tải script generate_user_info.py. Đây là mã nguồn Python đọc được, bạn (hoặc trợ lý AI) nên mở ra đọc trước khi chạy. Script đọc mã phần cứng và địa chỉ MAC của máy để tạo mã thiết bị (lưu trong user.json, dùng cho giới hạn số thiết bị theo cấp tài trợ), gọi đúng một địa chỉ https://vnstocks.com/api/vnstock/user/profile (khoá gửi trong header, không nằm trên URL) để lấy tên tài khoản, rồi ghi user.json vào ~/.vnstock/.

Trên macOS và Linux:

wget https://vnstocks.com/files/generate_user_info.py -O ~/Downloads/generate_user_info.py

Trên Windows, dùng PowerShell:

Invoke-WebRequest -Uri 'https://vnstocks.com/files/generate_user_info.py' -OutFile "$env:USERPROFILE\Downloads\generate_user_info.py"

Hoặc tải thẳng từ vnstocks.com/files/generate_user_info.py.

Bước 2. Lấy khoá API tại trang tài khoản.

Bước 3. Mở cửa sổ dòng lệnh tại thư mục chứa script rồi chạy. Script sẽ hỏi khoá, bạn dán khoá vào dấu nhắc đó. Đừng ghi khoá thẳng vào dòng lệnh: dòng lệnh được lưu trong lịch sử của cửa sổ dòng lệnh.

macOS và Linux:

cd ~/Downloads
python3 generate_user_info.py

Windows (Command Prompt hoặc PowerShell):

cd $env:USERPROFILE\Downloads
python generate_user_info.py

Bước 4. Script chạy xong sẽ báo tạo tệp thành công. Tệp nằm ở ~/.vnstock/user.json trên macOS và Linux, hoặc %USERPROFILE%\.vnstock\user.json trên Windows.

Bước 5. Chạy lại code Python của bạn.

1.6. Nhập sai API Key khi dùng công cụ dòng lệnh

Thay vì cài lại từ đầu, hãy ghi đè bằng biến môi trường trước khi chạy tập lệnh cài đặt:

export VNSTOCK_API_KEY="KEY_CHUAN_CUA_BAN"
./vnstock-cli-installer.run --non-interactive

1.7. Trình cài đặt giao diện báo lỗi thất bại

• Dấu hiệu: Giao diện đồ hoạ hiển thị lỗi màu đỏ, cửa sổ dòng lệnh báo thiếu thư viện đi kèm.

• Khắc phục: Đóng giao diện, chạy lệnh sau để bổ sung đầy đủ thư viện phụ trợ, sau đó mở lại trình cài đặt vnstock-installer.

  Shell

  pip install -r https://vnstocks.com/files/requirements.txt

1.8. Báo thiếu pip

• Dấu hiệu: No module named pip.

• Khắc phục: Chạy lệnh sau để nâng cấp hoặc cài đặt pip:

  Shell

  python -m ensurepip --upgrade

  Hoặc nếu bạn dùng uv:

  Shell

  uv pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai

1.9. Thiếu thư viện hệ thống vnii

• Dấu hiệu: Hệ thống báo thiếu thư viện vnii, hoặc bản vnii đang có gây xung đột khi import.

• Khắc phục: Cài lại gói này:

  Shell

  pip install --extra-index-url https://vnstocks.com/api/simple vnii

  Nếu máy có nhiều phiên bản Python hoặc bạn dùng môi trường ảo, kích hoạt đúng môi trường rồi chỉ định phiên bản:

  Shell

  python3.10 -m pip install --extra-index-url https://vnstocks.com/api/simple vnii

  Cài xong thì chạy lại code Python của bạn.

1.10. Lỗi vòng lặp xác thực hoặc hệ thống không nhận tài khoản

• Dấu hiệu: Hệ thống không nhận diện đúng cấp tài trợ hoặc liên tục yêu cầu xác thực.

• Khắc phục triệt để: Gỡ cài đặt hoàn toàn và thiết lập lại.

  Bước 1, gỡ thư viện:

  Shell

  pip uninstall vnstock vnai vnii vnstock_data vnstock_ta vnstock_news vnstock_pipeline vnstock_installer -y

  Bước 2, xoá cấu hình cũ. Trên macOS/Linux:

  Shell

  rm -rf ~/.vnstock

  Trên Windows:

  BATCH

  rmdir /S /Q %USERPROFILE%\.vnstock

  Bước 3, cài lại trình cài đặt và chạy:

  Shell

  pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.3
  vnstock-installer

1.11. Cài đặt báo không tìm thấy gói, hoặc cài nhầm trình cài 99.0.0

• Dấu hiệu: Cài vnstock hoặc vnai thì báo ERROR: Could not find a version that satisfies the requirement vnai (from versions: none) hay No matching distribution found. Hoặc pip show vnstock_installer hiện phiên bản 99.0.0 và lệnh vnstock-installer không mở được giao diện.

• Nguyên nhân: vnstock và vnai được phân phối từ kho gói của Vnstock, lệnh cài thiếu địa chỉ kho này thì pip không tìm thấy. Riêng tên vnstock-installer trên PyPI đã bị một bên khác đăng ký với số hiệu 99.0.0; pip luôn chọn số hiệu cao nhất trong mọi kho, nên lệnh không ghim phiên bản sẽ cài nhầm gói đó.

• Khắc phục: Luôn thêm --extra-index-url https://vnstocks.com/api/simple, và ghim phiên bản trình cài:

  Shell

  pip uninstall -y vnstock_installer
  pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai
  pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.3

2. Lỗi môi trường Python (macOS/Linux)

2.1. Lệnh Python nhận nhầm phiên bản

Bước 1. Sau khi kích hoạt môi trường ảo, kiểm tra đường dẫn của phiên bản bạn muốn:

which python3.14

Trên Windows với PowerShell:

Get-Command python3.14 | Select-Object Source

Bước 2. Gọi thẳng phiên bản cụ thể khi chạy code, thay vì python hay python3:

python3.14 your_script.py

Bước 3. Hoặc đặt bí danh trong Terminal. Trên macOS và Linux, thêm vào ~/.zshrc hoặc ~/.bash_profile:

alias python='python3.14'
alias python3='python3.14'

Rồi nạp lại: source ~/.zshrc.

Trên Windows với PowerShell, đặt bí danh trong profile, thay đường dẫn bằng đường dẫn thật trên máy bạn:

Set-Alias -Name python -Value C:\Python314\python.exe -Option AllScope -Scope CurrentUser -Force
Set-Alias -Name python3 -Value C:\Python314\python.exe -Option AllScope -Scope CurrentUser -Force

Bước 4. Xác nhận phiên bản đang dùng và các thư viện đã cài:

python3.14 --version
python3.14 -m pip list | grep vnstock

2.2. Lỗi môi trường bị quản lý bởi hệ thống

• Dấu hiệu: Báo lỗi error: externally-managed-environment trên hệ điều hành Linux/macOS phiên bản mới.

• Khắc phục: Hệ điều hành khoá cài đặt vào Python hệ thống. Cài vào môi trường ảo cố định ~/.venv (tạo nếu chưa có) bằng chính Python của môi trường đó; đừng thêm --break-system-packages hay dùng sudo pip.

  Shell

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

  Nếu ~/.venv đã có bản 4.x, xem Cài vào đâu trước khi cài.

3. Lỗi cài đặt trên Windows

3.1. Xung đột ứng dụng (mở Microsoft Store thay vì Python)

• Dấu hiệu: Bạn đã cài đặt Python nhưng khi mở Terminal và gõ lệnh python, thay vì chạy chương trình, Windows lại tự động mở Microsoft Store hoặc báo lỗi không tìm thấy lệnh.

• Nguyên nhân: Đây là do cơ chế "App Execution Aliases" (Biệt danh thực thi ứng dụng) của Windows 10/11. Mặc định, Windows đặt sẵn các file ảo (stubs) có tên python.exe và python3.exe trong hệ thống. Khi bạn tự cài Python nhưng quên chọn "Add Python to PATH" hoặc Windows vẫn ưu tiên Alias của hệ thống, nó sẽ gọi nhầm file ảo của Store thay vì Python bạn vừa cài.

• Giải pháp triệt để:

  • Bước 1: Gỡ bỏ bản Python từ Microsoft Store (nếu có) Để tránh xung đột đường dẫn và phiên bản, Vnstock khuyến nghị bạn chỉ nên dùng bản bộ cài chính thức từ python.org. Hãy gỡ cài đặt các bản Python tải từ Store.

    Bước 1: Tìm kiếm App Execution Aliases

  • Bước 2: Tắt "App Execution Aliases" Đây là bước quan trọng nhất để Windows "quên" lối tắt dẫn tới Store.

    1. Gõ "App Execution Aliases" vào thanh tìm kiếm Windows (hoặc vào Settings > Apps > Advanced app settings > App execution aliases).
    2. Tìm các mục có tên Python, App Installer (python.exe), App Installer (python3.exe).
    3. Gạt công tắc sang OFF.
    Bước 2: Tìm mục Python

  • Bước 3: Cài lại Python đúng chuẩn Tải bộ cài từ python.org. Khi chạy file cài đặt, hãy tích vào ô "Add Python.exe to PATH" ở ngay màn hình đầu tiên trước khi nhấn Install.

    Bước 3: Tắt Alias

3.2. Thiếu bộ biên dịch C++

Bước 1. Mở trang tải chính thức: Microsoft VC++ Redistributable Downloads.

Bước 2. Tìm mục "Latest supported redistributable version" và chọn v14 for Visual Studio 2017–2026. Đây là bản mới nhất, tương thích với các thư viện Python hiện đại.

Bước 3. Tải tệp đúng kiến trúc máy:

Không chắc thì tải cả hai, cài cả hai cũng không sao.

Bước 4. Chạy tệp .exe vừa tải, chọn "Install" hoặc "Agree and Install", chờ khoảng một đến hai phút rồi nhấn "Finish".

Bước 5. Chạy lại trình cài đặt Vnstock:

python -m vnstock_installer

Trình cài đặt sẽ nhận ra Visual C++ đã có và build tiếp vnstock_pipeline với vnstock_ta.

4. Lỗi tích hợp Jupyter và Google Colab

4.1. Jupyter Notebook không nhận thư viện

Bước 1. Kích hoạt môi trường ảo. Dòng lệnh hiện (.venv) ở đầu là đúng.

Bước 2. Cài thư viện kết nối:

python -m pip install ipykernel

Bước 3. Đăng ký Kernel với Jupyter:

python -m ipykernel install --user --name=vnstock-venv --display-name "Python (Vnstock)"

Bước 4. Mở Notebook, bấm nút chọn Kernel ở góc trên bên phải, chọn Python (Vnstock). Không thấy thì khởi động lại IDE.

4.2. Google Colab không nhận thư viện, hoặc xung đột numpy và pandas

• Dấu hiệu: Đã cài bằng !pip install nhưng báo lỗi khi import, hoặc báo xung đột phiên bản numpy, pandas.
• Khắc phục: Khởi động lại phiên làm việc: menu Runtime > Restart session. Colab sẽ nạp đúng các phiên bản thư viện vừa cài.

Khởi động lại phiên làm việc trên Google Colab

5. Xác minh cài đặt

Sau khi cài đặt, bạn có thể chạy đoạn mã sau để kiểm tra:

try:
    import vnstock
    print(f"✅ Vnstock bản Cộng đồng: {vnstock.__version__}")
except ImportError:
    print("❌ Vnstock chưa được cài đặt.")

# Kiểm tra các gói tài trợ
packages = ['vnstock_data', 'vnstock_news', 'vnstock_ta', 'vnstock_pipeline']
for pkg in packages:
    try:
        module = __import__(pkg)
        print(f"✅ {pkg} đã cài đặt thành công")
    except ImportError:
        print(f"⚪ {pkg} chưa cài đặt (Kiểm tra lại gói tài trợ của bạn)")

6. Quy trình cập nhật thư viện

Khi thấy thông báo [VNSTOCK INSIDER] 🚀 Có phiên bản gói tài trợ mới! hoặc 📦 Vnstock … is available, bạn không cần gỡ gì cả. Mở Terminal (hoặc Command Prompt), kích hoạt đúng môi trường ảo đang dùng rồi chạy lại trình cài. Trình cài tự nâng vnai, vnii, vnstock và các thư viện bản Mở rộng lên bản mới nhất trong một lượt:

• Trình cài giao diện (Windows, macOS):

  Shell

  pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock_installer==3.1.3
  vnstock-installer

• Trình cài dòng lệnh (Linux, máy chủ, Colab): tải bản mới rồi chạy:

  Shell

  curl -sL https://vnstocks.com/files/vnstock-cli-installer.run -o vnstock-cli-installer.run
  bash vnstock-cli-installer.run

Chỉ muốn cập nhật phần lõi thì chạy pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai. Cập nhật xong, khởi động lại chương trình Python, kernel Jupyter hoặc phiên Colab để mã mới được nạp.

Nếu cập nhật xong vẫn lỗi, cài lại từ đầu:

1. Gỡ bỏ toàn bộ thư viện liên quan:

   Shell

   pip uninstall vnstock vnai vnii vnstock_installer vnstock_data vnstock_ta vnstock_news vnstock_pipeline -y

2. Cài lại phần lõi và nhóm tiện ích:

   Shell

   pip install --extra-index-url https://vnstocks.com/api/simple vnstock vnai vnii vnstock_installer==3.1.3

3. Cài lại các thư viện bản Mở rộng thông qua công cụ Vnstock Installer.

Nhờ trợ lý AI làm thay cũng được: dán thông báo cập nhật vào khung trò chuyện, kèm câu "Cập nhật theo hướng dẫn tại vnstocks.com/files/vibe-onboarding.md".

7. Vẫn chưa xong?

Nếu đã thử hết mà lỗi còn nguyên, hãy xem Hỗ trợ từ xa và gửi kèm ba thông tin: hệ điều hành, phiên bản Python, và bản ghi lỗi đầy đủ.