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. Đã nâng cấp nhưng vẫn báo bản cộng đồng

Đây là bối rối phổ biến nhất của các thành viên sau khi tham gia 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à bị giới hạn 60 yêu cầu/phút.

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

Bạn đang chạy code dựa trên thư viện vnstock công khai (cài bằng lệnh pip install vnstock thông thường). Thư viện miễn phí vnstock không thể tự chuyển đổi hoặc mở rộng tính năng của gói tài trợ. Các gói tài trợ sử dụng một bộ thư viện độc lập cần cài đặt riêng nhưng hỗ trợ chuyển đổi code dễ dàng.

Cách xử lý

1. Cài đặt thư viện tài trợ: Bộ thư viện dành cho nhà tài trợ là các gói mã nguồ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 gói tài trợ.

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 miễn phí):
     Python

     from vnstock import Quote, Listing

   • Cách mới (Bản tài trợ):
     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 hạn mức truy cập của gói tài trợ (180 đến 600 yêu cầu/phút tương ứng với hạng Bronze, Silver, Golden, Diamond).

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 gói 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:

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

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.min.py.

Trên macOS và Linux:

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

Trên Windows, dùng PowerShell:

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

Hoặc tải thẳng từ vnstocks.com/files/generate_user_info.min.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, thay API_KEY_CUA_BAN bằng khoá thật:

macOS và Linux:

cd ~/Downloads
python3 generate_user_info.min.py --api-key API_KEY_CUA_BAN

Windows với Command Prompt:

cd %USERPROFILE%\Downloads
python generate_user_info.min.py --api-key API_KEY_CUA_BAN

Windows với PowerShell:

cd $env:USERPROFILE\Downloads
python generate_user_info.min.py --api-key API_KEY_CUA_BAN

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 vnstock

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 gói 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

  vnstock-installer

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: Do hệ điều hành đã khoá cài đặt toàn cục, bạn bắt buộc tạo môi trường ảo và kích hoạt nó, sau đó mới tiến hành cài đặt. Tuyệt đối không cài thư viện ra ngoài môi trường chung.

  Shell

  python3 -m venv .venv
  source .venv/bin/activate

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 phiên bản miễn phí: {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

Vnstock thường xuyên phát hành các bản vá lỗi và tính năng mới. Cách an toàn nhất để đảm bảo ổn định khi cập nhật là:

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:

   Shell

   pip install vnstock vnai

3. Cài lại nhóm tiện ích:

   Shell

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

4. Cài lại các gói mở rộng chuyên sâu thông qua công cụ Vnstock Installer.

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 đủ.