ติดตั้งแพ็กเกจ Qiskit v1.0 ใหม่

Qiskit v1.0 ใช้โครงสร้างแพ็กเกจที่แตกต่างจากเวอร์ชันก่อนหน้า และอาจทำให้เกิดปัญหาในสภาพแวดล้อมที่ใช้แพ็กเกจซึ่งยังไม่พร้อมรองรับ Qiskit v1.0

ข้อควรระวัง

อย่าพยายามอัพเกรด Python virtual environment ที่มีอยู่แล้วไปยัง Qiskit v1.0 โดยตรง

เราจะไม่ทำการเปลี่ยนแปลงที่ breaking เช่นนี้ในอนาคตอีก นี่เป็นเหตุการณ์ครั้งเดียวที่เกิดขึ้นในการเปิดตัว Qiskit v1.0 โดยเฉพาะเพื่อให้การจัดการแพ็กเกจในอนาคตเป็นเรื่องง่ายที่สุด

คู่มือนี้แบ่งออกเป็นหัวข้อต่างๆ ดังนี้ อ่านเฉพาะหัวข้อที่เกี่ยวข้องกับตัวเองก็พอ

ผู้ใช้ทั่วไปควรอ่านส่วน สำหรับผู้ใช้
ถ้าพัฒนาหรือดูแลแพ็กเกจที่พึ่งพา Qiskit ให้อ่านส่วน สำหรับนักพัฒนา
ถ้าเจอปัญหาในการติดตั้งหรือ import Qiskit v1.0 ให้ดูส่วน การแก้ปัญหา

ถ้าสนใจทำความเข้าใจโครงสร้างแพ็กเกจเดิมและสาเหตุที่มันเปลี่ยน ให้ดู ภาพรวมของการเปลี่ยนแปลงแพ็กเกจที่ breaking

สำหรับผู้ใช้

ต้องสร้าง virtual environment ใหม่เพื่อติดตั้ง Qiskit v1.0 การอัพเกรด installation ที่มีอยู่แล้วเป็น Qiskit v1.0 โดยตรงนั้นยุ่งยากและเสี่ยงต่อข้อผิดพลาดมาก

หมายเหตุ

ตัวอย่างในส่วนนี้ใช้โมดูล venv ที่เป็นส่วนหนึ่งของ Python standard library ถ้าใช้เครื่องมืออื่น เช่น virtualenv หรือ conda ให้ดูเอกสารของมันเพื่อขอความช่วยเหลือ

สำหรับคำสั่งบน Linux และ macOS ใช้ syntax แบบ bash สำหรับ Windows ใช้ PowerShell

สร้าง environment ใหม่

สร้าง virtual environment ใหม่ในแต่ละ project directory ที่กำลังทำงานอยู่ โดยใช้ Python 3.8 ขึ้นไปตามที่ต้องการ
- macOS
- Linux
- Windows
python3 -m venv .venv
python3 -m venv .venv
python -m venv .venv

Activate environment

macOS
Linux
Windows

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.ps1

ติดตั้งแพ็กเกจตามต้องการ ควรทำโดยใช้คำสั่ง pip install เพียงคำสั่งเดียวพร้อม dependencies ทั้งหมดในครั้งเดียว
```
pip install 'qiskit>=1'
```
สามารถเพิ่มแพ็กเกจอื่นๆ ได้โดยระบุเป็น arguments เพิ่มเติม เช่น:
```
pip install 'qiskit>=1' jupyterlab pandas matplotlib
```
Qiskit v1.0 มีการเปลี่ยนแปลงที่ breaking ดังนั้นหลายแพ็กเกจจึงถูกทำเครื่องหมายว่ายังไม่รองรับ ดังนั้นอาจเห็น error จาก pip จนกว่าแพ็กเกจเหล่านั้นจะออกเวอร์ชันใหม่ แพ็กเกจเวอร์ชันเก่าอาจยังพึ่งพา qiskit-terra แบบ legacy ด้วย แพ็กเกจเหล่านั้นอาจไม่แสดง error ตอนรันคำสั่งนี้ แต่อาจเกิด error ตอนรัน import qiskit ไม่ควรติดตั้งแพ็กเกจใดๆ ที่พึ่งพา qiskit-terra โดยตรง
เคล็ดลับ
วิธีหนึ่งในการสั่งให้ pip ห้าม qiskit-terra จากคำสั่ง install แต่ละคำสั่งคือใช้ constraints file ที่กำหนดให้ qiskit-terra อยู่ที่เวอร์ชันที่เป็นไปไม่ได้ เช่น constraints file ที่มีบรรทัด qiskit-terra>=1.0 จะทำให้ถ้า dependency ใดพยายามติดตั้ง qiskit-terra จะไม่มีเวอร์ชันที่ตีพิมพ์แล้วตรงกับ requirements
เราได้จัดทำไฟล์ดังกล่าวใน GitHub Gist ที่ https://qisk.it/1-0-constraints ซึ่งสามารถใช้ได้ดังนี้:
pip install -c https://qisk.it/1-0-constraints qiskit [other packages]
ถ้าแพ็กเกจใดต้องการ qiskit-terra จะเห็น resolution failure
ข้อควรระวัง
อย่าติดตั้งแพ็กเกจที่ไม่เข้ากันกับ Qiskit v1.0 ใน virtual environment นี้ ถ้าจำเป็นต้องใช้แพ็กเกจเหล่านั้น ให้ติดตั้งใน virtual environment แยกต่างหากพร้อม Qiskit 0.45 หรือ 0.46

ถ้ามี environment เดิมอยู่แล้ว สามารถใช้ pipdeptree เพื่อ query requirements ของแพ็กเกจที่ติดตั้งอยู่เพื่อดูว่ามีตัวไหนที่ต้องการ qiskit<1 หรือไม่ สำหรับตัวที่ต้องการ qiskit<1 ให้ตรวจสอบการอัพเดตที่ทำให้เข้ากันได้กับ Qiskit v1.0

ถ้าเจอปัญหา ให้ดูส่วน การแก้ปัญหา หรือถามใน Qiskit Slack ถ้าคิดว่ามี bug สามารถ สร้าง issue ให้ Qiskit ได้
ถ้ายังไม่ได้วางแผนจะใช้ environment ทันที ให้ใช้คำสั่ง deactivate เพื่อออกจาก environment

ใช้งาน environment ใหม่

ทุกครั้งที่เริ่ม session command line ใหม่ ต้องนำทางไปยัง project directory และ "activate" environment โดยรันคำสั่ง activate:

macOS
Linux
Windows

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.ps1

สำหรับนักพัฒนา

ถ้าดูแลแพ็กเกจที่พึ่งพา Qiskit ใช้ข้อมูลนี้เพื่อเรียนรู้วิธีระบุความเข้ากันได้อย่างถูกต้องและทดสอบกับ Qiskit v1.0

คำแนะนำสำหรับ requirements

เราแนะนำให้แพ็กเกจของตัวเองกำหนด qiskit>=0.45,<1 (หรือ lower bound อื่นที่เหมาะสม) ถ้ายังไม่แน่ใจว่าแพ็กเกจนั้นเข้ากันได้กับ Qiskit v1.0 หรือไม่ นี่คือ คำแนะนำเดียวกับที่ให้สำหรับความเข้ากันได้กับ NumPy 2.0

Qiskit v1.0 release candidate เวอร์ชัน 1.0.0rc1 จะเปิดตัวในวันที่ 1 กุมภาพันธ์ 2024 ควรทดสอบแพ็กเกจกับ release candidate นี้ และโดยเร็วที่สุดให้ออก (compatible) เวอร์ชันใหม่ของแพ็กเกจโดยถอด upper requirement pin ออก

คำแนะนำสำหรับการทดสอบกับ Qiskit v1.0

คำแนะนำเหล่านี้ใช้สำหรับการทดสอบเชิงรุกกับ branch main ของ Qiskit และสำหรับการทดสอบกับ release candidate v1.0.0rc1 (และเวอร์ชันหลังจากนั้นถ้ามี)

เราไม่แนะนำให้ทำ branch-protect บน CI success กับ branch main ของ Qiskit ในตอนแรก เนื่องจากการเปลี่ยนแปลงของ Qiskit อาจทำให้ merge PR ไม่ได้ หลังจาก Qiskit release candidate ออกมาแล้ว และหลังจาก dependencies ทั้งหมดของแพ็กเกจรองรับ Qiskit v1.0 แล้ว เรา แนะนำ ให้ทำ branch-protect บน success กับ release candidate ล่าสุด เพื่อให้มั่นใจว่าแพ็กเกจยังคงเข้ากันได้กับ Qiskit v1.0

ถ้าทั้งแพ็กเกจและ transitive dependencies ทั้งหมดของมันไม่มีการ pin requirement ที่ qiskit<1 ให้สร้าง testing virtual environment ตามปกติในคำสั่ง pip install เดียว และระบุ qiskit==1.0.0rc1 หรือ qiskit==git+https://github.com/Qiskit/qiskit.git@main ตามที่เหมาะสม นี่เป็นวิธีที่น่าเชื่อถือที่สุดในการให้มั่นใจว่ามี environment ที่ valid อย่างสมบูรณ์

ถ้า component เดียวใน dependency graph ของแพ็กเกจที่มีการ pin requirement ที่ qiskit<1 คือแพ็กเกจของตัวเองเท่านั้น อาจต้องการให้ CI suite patch requirements file ชั่วคราวเพื่ออนุญาต Qiskit v1.0 ก่อน จากนั้นติดตั้ง environment ในขั้นตอนเดียวเหมือนเดิม หรือใช้กฎต่อไปนี้สำหรับการอัพเกรด environment แบบทั่วไป แต่เปลี่ยนเป็น single-environment resolution โดยเร็วที่สุดเท่าที่ทำได้

ถ้า transitive dependency อย่างน้อยหนึ่งตัวยังไม่มีเวอร์ชัน release ที่อนุญาตรองรับ Qiskit v1.0 ต้องทำการเปลี่ยนแปลงด้วยตนเอง มีหลายกลยุทธ์ที่ลองได้ เรียงตามลำดับความชอบโดยประมาณ (ชอบที่สุดไปน้อยที่สุด):

ติดตั้ง problematic dependency จาก branch main ของมันเอง ถ้าเวอร์ชัน development ผ่อนคลาย pin แล้ว เพื่อให้สร้าง test environment ได้ในขั้นตอนเดียว
ยกเว้นการใช้ dependency นั้นออกจาก test environment ถ้าทำได้
สร้าง test environment แบบเดิมตามปกติ จากนั้น override ด้วยตนเองเพื่อใช้ Qiskit v1.0

อัพเกรด environment เดิมด้วยตนเอง

ข้อควรระวัง

กระบวนการนี้สร้าง environment ที่ invalid โดยเจตนา ดังนั้นการทดสอบใดๆ ที่ใช้มันจะมีความ valid น้อยลง การทดสอบอาจดูเหมือนผ่าน แต่นั่นไม่รับประกันว่าแพ็กเกจเข้ากันได้กับ Qiskit v1.0 ซึ่งอาจเกิดขึ้นเพราะ environment ไม่ self-consistent และอาจมีไฟล์ที่ไม่มีอยู่ใน valid environment หรือ behavior ของแพ็กเกจที่ถูก override อาจเปลี่ยนไปกับ Qiskit v1.0

หมายเหตุ

ถ้า dependency ตัวหนึ่งของ pin qiskit<1 แม้แต่ใน development branch ของมัน มันอาจไม่ทำงานกับ Qiskit v1.0 ได้เลย และถ้าการทดสอบรันไม่ได้เพราะสิ่งนี้ อาจต้องรอให้มันหรือร่วมมือกับมันเพื่อให้รองรับ

ในการอัพเกรด environment แบบ in situ ให้ทำตามขั้นตอนเหล่านี้:

สร้าง environment ตามปกติ โดยให้แน่ใจว่าไม่มีแพ็กเกจที่ extend namespace qiskit หรือ qiskit.providers ติดตั้งอยู่
Uninstall ทั้ง qiskit และ qiskit-terra เพื่อให้แน่ใจว่าไม่มีตัวไหนอยู่:

pip uninstall --yes qiskit qiskit-terra

ณ จุดนี้ site-packages ของ environment ไม่ควรมี directory qiskit อยู่ ไม่จำเป็นต้องตรวจสอบในทุก CI run แต่ถ้ากำลัง debug script ในเครื่อง ให้ทำตามขั้นตอนเหล่านี้เพื่อตรวจสอบ:

รันคำสั่งต่อไปนี้จากภายใน python ของ virtual environment:

import site
print(site.getsitepackages())

ตรวจสอบว่า directory เหล่านั้นไม่มี directory qiskit ถ้ามี แสดงว่าน่าจะมีแพ็กเกจที่ extend namespace ติดตั้งอยู่ และควรหาและลบ dependency เหล่านั้น
ติดตั้ง Qiskit v1.0 เวอร์ชันเป้าหมายด้วยคำสั่งใดคำสั่งหนึ่งเหล่านี้:

หลังจาก release candidate ที่ต้องการถูกเผยแพร่แล้ว:
```
pip install 'qiskit==1.0.0rc1'
```
สำหรับ dependency จาก branch main (หรือแทนที่ด้วย git revision identifier ที่ต้องการหลัง @)
```
pip install 'git+https://github.com/Qiskit/qiskit.git@main'
```

ตอนนี้มี environment ที่ Qiskit อนุญาตให้ทดสอบได้แล้ว ถ้า import qiskit ส่งผล ImportError หรือถ้ากำลังดิ้นรนหา dependencies ให้ดูคำแนะนำในส่วนเกี่ยวกับ invalid-environment protections ใน Qiskit

ตัวอย่าง GitHub Actions workflows แบบ manual

workflows ต่อไปนี้ตั้งค่า scheduled job ให้รันในตอนกลางคืน job นี้ตั้งค่า testing environment สำหรับ Qiskit v1.0 และรัน pytest (หรือขั้นตอนการทดสอบอื่นๆ ที่ต้องการ)

สำหรับแพ็กเกจที่ไม่มี transitive dependencies ที่ pin qiskit<1:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          # First ensure the standard tools are up-to-date.
          python -m pip install --upgrade pip wheel setuptools
          # Note that this resolves everything in a single command.
          # If it fails, at least one package likely requires `qiskit<1`.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            . \
            'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

สำหรับแพ็กเกจที่มี transitive dependencies ที่ pin qiskit<1 อย่างหลีกเลี่ยงไม่ได้ ให้สร้าง invalid environment:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          python -m pip install --upgrade pip wheel setuptools
          # Install the regular test environment.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            .
          # Uninstall `qiskit` and `qiskit-terra`.
          python -m pip uninstall --yes qiskit qiskit-terra
          # Install the new version of Qiskit
          python -m pip install 'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

ตัวอย่าง `tox` configuration

ต่อไปนี้คือตัวอย่างส่วนของ tox.ini สำหรับสร้าง testing environment สำหรับ Qiskit v1.0 และรัน pytest (หรือขั้นตอนการทดสอบอื่นๆ ที่ต้องการ)

ถ้าไม่มีอะไรขัดขวางการติดตั้ง Qiskit v1.0 ใน valid environment:

[tox]
minversion = 4.0.0

# This environment section should set up your regular test build.
# We'll extend it after, and this one is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest

# This is an override environment to install Qiskit main.
# We're assuming that you have a requirement like `qiskit>=0.45`
# in your packages metadata requirements.
[testenv:qiskit-main]
# Inherit the base dependencies, and add the additional requirement.
deps =
  [{testenv}deps]
  git+https://github.com/Qiskit/qiskit@main
# All other options, like the `commands` section, are inherited from `testenv`.

ถ้าแพ็กเกจหรือ transitive dependency มีการ pin qiskit<1 อย่างหลีกเลี่ยงไม่ได้ เราแนะนำให้ทำการทดสอบนี้โดยใช้การสร้าง environment ด้วยตนเองตามที่อธิบายในส่วนด้านบน เพราะ tox มีความซับซ้อนหลายอย่างเนื่องจากความเข้มงวดมากขึ้นเกี่ยวกับ environment isolation และลำดับการติดตั้ง นี่เป็น behavior ที่ถูกต้องของ tox (เราไม่ควรสร้าง invalid environment) แต่เพราะเรารู้อยู่แล้วว่ากำลังสร้าง invalid environment การตรวจสอบเหล่านี้จึงกลายเป็นอุปสรรค

[tox]
minversion = 4.0.0

# This environment section should set up your regular test build.
# We'll extend it later.  This is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest

[testenv:qiskit-main]
# Set a sequence of commands to run in the environment 
# after everything has been installed,
# but before the main test suite.
commands_pre =
  pip uninstall --yes qiskit qiskit-terra
  pip install 'git+https://github.com/Qiskit/qiskit@main'
# All other sections, like the dependencies and the 'commands' section 
# are inherited.

การแก้ไขปัญหา

การเปลี่ยนแปลงการแพ็กเกจรอบ Qiskit v1.0 นั้นซับซ้อน และเครื่องมือมาตรฐานอย่าง pip ของ Python ก็ยังไม่ครอบคลุมพอที่จะสื่อสารการเปลี่ยนแปลงโครงสร้างการแจกจ่ายเหล่านั้นได้ ซึ่งอาจทำให้เกิดปัญหากับผู้ใช้ เราพยายามทำให้ Qiskit แจ้งข้อผิดพลาดได้เร็วและชัดเจนหากตรวจพบสภาพแวดล้อมที่ไม่ถูกต้อง โดยไม่แจ้งเตือนเกินจริง เราเข้าใจว่าผู้ใช้อาจรู้สึกรำคาญกับข้อความแสดงข้อผิดพลาด แต่จากประสบการณ์ของเรา การรับรู้ปัญหาตั้งแต่เนิ่นๆ ดีกว่าการปล่อยให้ทุกอย่างดูเหมือนทำงานได้ แล้วค่อยล้มเหลวในแบบที่แยกยากในภายหลัง

ส่วนนี้รวบรวมข้อผิดพลาดด้านการแพ็กเกจที่อาจพบ พร้อมคำแนะนำในการแก้ไข

ปัญหาส่วนใหญ่เหล่านี้ไม่ได้เป็นเรื่องเฉพาะของ Qiskit ดังนั้นคำแนะนำนี้น่าจะมีประโยชน์ แม้ว่าส่วนที่มีปัญหาจะไม่ได้เกี่ยวข้องกับ Qiskit ก็ตาม

`import qiskit` แจ้ง "ModuleNotFoundError: No module named 'qiskit'"

Python ไม่พบการติดตั้ง Qiskit ของคุณ

ถ้าติดตั้ง Qiskit ไปแล้วแน่นอน แสดงว่าอาจยังไม่ได้เปิดใช้งาน virtual environment ที่ถูกต้อง ดูคำแนะนำได้ที่ส่วนการเปิดใช้งาน virtual environment

ถ้าใช้ Jupyter และพบปัญหานี้ ให้ตรวจสอบว่า Jupyter ติดตั้งอยู่ใน virtual environment เดียวกับ Qiskit ออกจาก Jupyter เปิดใช้งาน virtual environment ของ Qiskit บน command line แล้วรัน pip install jupyterlab (หรือ notebook interface ที่ใช้อยู่) จากนั้นเปิด Jupyter ใหม่

`import qiskit` สำเร็จ แต่พอลองทำอะไรก็ได้ "AttributeError: module 'qiskit' has no attribute '...'"

ปัญหานี้น่าจะเกิดจากการที่สภาพแวดล้อมมี Qiskit เวอร์ชันเก่าอยู่ร่วมกับแพ็กเกจที่ขยาย namespace ของมัน (เช่น Qiskit Aer เวอร์ชันเก่า หรือ Qiskit IBM Q® Provider ที่เลิกใช้งานแล้ว) แล้วถูก uninstall Qiskit ออกไป วิธีที่ง่ายที่สุดคือสร้าง virtual environment ใหม่ และติดตั้งเฉพาะแพ็กเกจล่าสุดที่ยังคงใช้งานได้เท่านั้น

ถ้าเพิ่งสร้าง virtual environment ใหม่ หรือแน่ใจว่าแพ็กเกจเดิมไม่ใช่ปัญหา ให้ตรวจสอบว่า working directory ปัจจุบัน (โฟลเดอร์ที่ shell session อยู่ตอนเปิด Python / Jupyter) ไม่มีโฟลเดอร์ชื่อ qiskit กฎเริ่มต้นของ Python จะค้นหา working directory ปัจจุบันก่อนเสมอใน search path เมื่อพยายาม import โมดูล ดังนั้นโฟลเดอร์ที่มีชื่อซ้ำกันอาจทำให้เกิดปัญหา import ได้

`pip` ปฏิเสธที่จะติดตั้งบางแพ็กเกจพร้อมกัน

หลังจากรันคำสั่ง pip install พร้อมหลายรายการ อาจพบข้อผิดพลาดเช่น:

ERROR: Cannot install qiskit-dynamics==0.4.4 and qiskit==1.0.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested qiskit==1.0.0
    qiskit-dynamics 0.4.4 depends on qiskit<1.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

นี่คือความขัดแย้งจริงๆ ไม่มีทางติดตั้งทุก distribution พร้อมกันได้

ในบริบทของ Qiskit v1.0 สาเหตุน่าจะมาจาก distribution ที่พยายามติดตั้งมีข้อกำหนดอย่าง qiskit<1.0 หมายความว่าผู้พัฒนา distribution นั้นระบุว่ายังไม่รองรับ Qiskit v1.0

สามารถ (อย่างสุภาพ) ถามผู้พัฒนาว่าจะปล่อยเวอร์ชันใหม่ที่รองรับ Qiskit v1.0 เมื่อไหร่ แต่ก่อนอื่นให้ตรวจสอบว่ามี issue หรือ pull request ที่เปิดอยู่แล้วสำหรับเรื่องนี้หรือไม่ โปรดเข้าใจว่าเรื่องนี้ต้องใช้เวลา กรุณาให้ผู้พัฒนาสักหนึ่งเดือนในการเตรียมเวอร์ชันใหม่ จนกว่าจะถึงตอนนั้น ก็ไม่สามารถติดตั้ง distribution นั้นพร้อมกับ Qiskit v1.0 ได้ ถ้ายังต้องการใช้ distribution นั้น ให้สร้าง virtual environment ใหม่และใช้ Qiskit 0.45 หรือ 0.46 (หรือเวอร์ชันที่รองรับ) ควบคู่กับแพ็กเกจอื่นนั้น

ข้อควรระวัง

ถ้าพบข้อผิดพลาดนี้ อย่าพยายามสร้างสภาพแวดล้อมโดยการเรียก pip install หลายครั้ง คำสั่งเหล่านั้นอาจไม่ล้มเหลว แต่จะสร้างสภาพแวดล้อมที่ไม่ถูกต้อง จากนั้นก็อาจเห็นข้อความแสดงข้อผิดพลาดอื่นๆ ที่อธิบายในส่วนนี้

อ่านเพิ่มเติมได้ที่เอกสารจาก Python packaging authority เรื่อง conflict resolution

`pip` สำเร็จแต่แสดงข้อผิดพลาดหลังรันคำสั่ง `pip install`

อาจเห็นข้อผิดพลาดใน output ของ pip เช่น:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behavior is the source of the following dependency conflicts.
some-distribution 0.4.4 requires qiskit>=0.44,<1, but you have qiskit v1.0.0 which is incompatible.

บรรทัดแรกมักจะเหมือนกันทุกครั้ง (ตั้งแต่ pip 23.3) แต่บรรทัดที่สองจะเปลี่ยนไปตามปัญหาที่เกิดขึ้น และอาจมีหลายบรรทัดแบบนี้ pip น่าจะแจ้งว่าทำสิ่งที่ต้องการสำเร็จแล้ว แม้จะมีข้อความแสดงข้อผิดพลาด

หมายความว่าสภาพแวดล้อมมีความขัดแย้งและไม่สามารถมั่นใจได้ว่าจะทำงานถูกต้อง ในการแก้ปัญหา ให้ตรวจสอบรายการข้อความจาก pip และพิจารณาว่าจำเป็นต้องใช้แพ็กเกจทั้งหมดที่มีข้อกำหนดขัดแย้งหรือไม่ บางครั้งอาจมีความขัดแย้งจริงๆ ระหว่าง dependencies คุณอาจต้องใช้ virtual environment หลายตัวเพื่อแยก dependencies ที่มีข้อกำหนดที่เข้ากันไม่ได้

ทางเลือกที่ปลอดภัยที่สุดคือเริ่ม virtual environment ใหม่ (หรือมากกว่าหนึ่งตัวถ้ามีความขัดแย้งจริงๆ) แล้วลบตัวที่ขัดแย้งทิ้ง

เมื่อตั้งค่า virtual environment ให้รันคำสั่ง pip install เพียงครั้งเดียวที่รวม dependencies ทั้งหมดที่ต้องการ นี่คือวิธีที่น่าเชื่อถือที่สุดสำหรับ pip ในการหาสภาพแวดล้อมที่ resolved อย่างถูกต้องโดยไม่มีความขัดแย้ง ถ้ายังคงมีปัญหาความขัดแย้งหลังจากตั้งค่าสภาพแวดล้อมแล้ว ให้หลีกเลี่ยงการรันคำสั่ง pip install หรือ pip uninstall เพิ่มเติม เพราะ pip ไม่รับประกันว่าจะรักษาความสอดคล้องของสภาพแวดล้อมในคำสั่งต่อๆ ไป

หมายเหตุ

ถ้ากังวลเรื่องการจัดการ virtual environment หลายตัว ขอให้มั่นใจว่าการพัฒนาและใช้งาน Python มักเกี่ยวข้องกับ virtual environment หลายตัว การสร้างตัวใหม่สำหรับโปรเจกต์แยกกันเป็นเรื่องปกติและเป็นแนวปฏิบัติที่ดี เมื่อใช้ virtual environment เสร็จแล้ว ก็แค่ลบโฟลเดอร์ทิ้ง ไม่จำเป็นต้องเก็บหลายสภาพแวดล้อมไว้ถาวร

`import qiskit` ขึ้น `ImportError`

เมื่อรัน import qiskit อาจเห็นข้อผิดพลาดเช่น:

ImportError: Qiskit is installed in an invalid environment that has both Qiskit 1.0+ and an earlier version. You should create a new virtual environment, and ensure that you do not mix dependencies between Qiskit pre-1.0 and post-1.0. Any packages that depend on 'qiskit-terra' are not compatible with Qiskit 1.0 and will need to be updated. Qiskit unfortunately cannot enforce this requirement during environment resolution.

เคล็ดลับ

อาจเคยรันคำสั่ง pip install ที่ถูกต้องทุกประการ ตามคำแนะนำทั้งหมดในคู่มือนี้ แล้วยังเห็นข้อความแสดงข้อผิดพลาดนี้อยู่ดี นั่นไม่ใช่ความผิดของคุณ แต่ข้อความแสดงข้อผิดพลาดยังถูกต้องอยู่ และ Qiskit ไม่สามารถโหลดได้อย่างปลอดภัย

ข้อผิดพลาดหมายความว่า Qiskit ติดตั้งอยู่ในสภาพแวดล้อมที่ไม่ถูกต้องซึ่งมีทั้ง Qiskit v1.0 และเวอร์ชันก่อนหน้า ลักษณะนี้เกิดจากการที่ distribution qiskit-terra ถูกติดตั้งร่วมกับ Qiskit v1.0 ตรวจสอบว่า distribution ใดติดตั้งอยู่ได้โดยรัน pip list แต่ไม่สามารถแก้ไขได้ด้วยการ uninstall qiskit-terra เพียงอย่างเดียว

น่าเสียดายที่ qiskit>=1.0 และ qiskit-terra เป็น distribution ที่ขัดแย้งกัน และไม่สามารถติดตั้งพร้อมกันได้ ยิ่งน่าเสียดายกว่านั้น เราไม่สามารถสื่อสารความขัดแย้งนี้ให้ pip รับรู้ได้ เนื่องจากข้อจำกัดของระบบ metadata ของมัน

ข้อผิดพลาดนี้มักเกิดขึ้นในสองสถานการณ์:

รันคำสั่งอย่าง pip install 'qiskit>=1' something-else และ something-else มีข้อกำหนดบน qiskit-terra
พยายามรัน pip install -U qiskit ในสภาพแวดล้อมที่มีอยู่แล้ว

ในทั้งสองกรณีนี้ ไม่มีการรับประกันว่า pip จะแสดงข้อความที่เป็นประโยชน์

เคล็ดลับ

วิธีหนึ่งในการบังคับให้ pip ห้าม qiskit-terra จากคำสั่ง install แต่ละคำสั่งคือการใช้ไฟล์ constraints ที่กำหนดให้ qiskit-terra เป็นเวอร์ชันที่เป็นไปไม่ได้ ตัวอย่างเช่น ไฟล์ constraints ที่มีบรรทัด qiskit-terra>=1.0 จะหมายความว่าถ้า dependency พยายามติดตั้ง qiskit-terra ก็จะไม่มีเวอร์ชันที่เผยแพร่แล้วที่ตรงกับข้อกำหนด

เราได้จัดเตรียมไฟล์ดังกล่าวไว้ใน GitHub Gist ที่ https://qisk.it/1-0-constraints ซึ่งสามารถใช้แบบนี้:

pip install -c https://qisk.it/1-0-constraints qiskit [other packages]

ถ้าแพ็กเกจใดต้องการ qiskit-terra จะเห็นความล้มเหลวในการ resolution

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit v1.0

ไม่ว่าจะเกิดขึ้นอย่างไร การสร้าง virtual environment ใหม่ง่ายกว่ามาก

ขั้นแรก ต้องหาว่าแพ็กเกจใดที่นำ dependency บน qiskit-terra เข้ามา ในสภาพแวดล้อมที่เสียหาย ให้ติดตั้ง pipdeptree จาก PyPI นี่คือเครื่องมือสำหรับสร้าง dependency graph:

pip install pipdeptree

ถามมันว่าแพ็กเกจใดที่นำ dependencies บน qiskit-terra และ qiskit เข้ามา (สองคำสั่งแยกกัน):

pipdeptree --reverse --package qiskit-terra

pipdeptree --reverse --package qiskit

output อาจมีลักษณะประมาณนี้:

qiskit-terra==0.45.2
└── qiskit-dynamics==0.4.2 [requires: qiskit-terra>=0.23.0]

qiskit==1.0.0
├── qiskit-aer==0.13.2 [requires: qiskit>=0.45.0]
└── qiskit-ibm-provider==0.8.0 [requires: qiskit>=0.45.0]

ในตัวอย่างด้านบน มี distribution สองตัวที่ประกาศว่าตัวเองรองรับ Qiskit v1.0 (qiskit-aer และ qiskit-ibm-provider) และหนึ่งตัวที่ยังมี dependency บน qiskit-terra

เคล็ดลับ

ตัวอย่างนี้เป็นโครงสร้าง dependency แบบแบน อาจเห็น tree ที่ลึกกว่านี้มาก แพ็กเกจที่ขึ้นตรงกับ qiskit-terra โดยตรง (การเยื้องน้อยที่สุด) น่าจะเป็นตัวที่มีปัญหามากที่สุด แต่ตัวที่อยู่ลึกกว่าในแผนผังก็อาจมีปัญหาได้ถ้ามัน depends บนเวอร์ชันเก่าๆ ของแพ็กเกจอื่นที่ได้รับการอัปเดตแล้ว

การเห็น dependency บน qiskit-terra อาจหมายความได้หลายอย่าง:

แพ็กเกจที่ depend เป็นแพ็กเกจเก่าและจะไม่มีการอัปเดตให้รองรับ Qiskit v1.0

ในกรณีนี้ ไม่มีทางใช้แพ็กเกจนั้นกับ Qiskit v1.0 ได้เลย และจะต้องใช้ Qiskit เวอร์ชันก่อนหน้าต่อไป โดยปกติลักษณะนี้คือแพ็กเกจที่ depend อยู่ที่เวอร์ชันล่าสุด (สมมติว่าสภาพแวดล้อมใหม่ และไม่ได้ pin เวอร์ชันให้ต่ำกว่า) และมีข้อกำหนดโดยตรงบน qiskit-terra
แพ็กเกจที่ depend เป็นแพ็กเกจที่ยังคงดูแลอยู่ แต่ยังไม่รองรับ Qiskit v1.0

ในกรณีนี้ ต้องรอให้ผู้พัฒนาปล่อยเวอร์ชันที่รองรับ กรุณาอดทนรอ! โดยปกติลักษณะนี้คือ distribution ที่ติดตั้ง ไม่ได้อยู่ที่เวอร์ชันล่าสุด แม้ว่าคำสั่งติดตั้งไม่ได้ระบุเวอร์ชัน ตรวจสอบเวอร์ชัน release ล่าสุดของ distribution ได้โดยค้นหาหน้าของมันที่ https://pypi.org/

pip น่าจะค้นหาเวอร์ชันเก่าๆ ของแพ็กเกจจนกว่าจะพบตัวที่ (อาจมาจากเดือนหรือปีก่อน) ขึ้นกับแค่ qiskit-terra

นี่คือสิ่งที่เกิดขึ้นในตัวอย่างด้านบน ตอนที่สร้างเอกสารนี้ qiskit-dynamics==0.4.4 เป็นเวอร์ชัน release ล่าสุด

ถ้าสร้างสภาพแวดล้อมนี้จากคำสั่ง pip install หลายคำสั่ง (เช่น สภาพแวดล้อมเก่าที่ได้รับการอัปเดต) ให้ลองติดตั้งแพ็กเกจทั้งหมดโดยใช้คำสั่ง pip install เพียงคำสั่งเดียวเมื่อสร้างสภาพแวดล้อมใหม่ก่อน ถ้าปัญหายังคงอยู่ อย่างน้อยหนึ่งในแพ็กเกจที่ต้องการน่าจะยังไม่รองรับ Qiskit v1.0 และ pip กำลังหาเวอร์ชันเก่าที่เชื่อว่าจะทำงานได้เพราะไม่รู้เกี่ยวกับความขัดแย้ง qiskit>=1/qiskit-terra

แทนที่จะทำแบบนั้น ให้ใช้คำสั่ง pipdeptree เพื่อระบุว่า dependencies ใดที่ยังไม่รองรับ Qiskit v1.0 ยกเว้นแพ็กเกจที่ยังไม่รองรับ Qiskit v1.0 เมื่อสร้างสภาพแวดล้อม Qiskit v1.0 หรือใช้ Qiskit เวอร์ชันก่อนหน้าต่อไป ดูคำแนะนำได้ที่สร้างสภาพแวดล้อมใหม่

หมายเหตุ

ตัวอย่างในส่วนนี้สร้างขึ้นก่อนที่ Qiskit v1.0 จะวางจำหน่าย

distribution "เก่า" ที่กล่าวถึง (qiskit-dynamics) มีพฤติกรรมที่ถูกต้อง มันยังไม่ทราบว่ารองรับ Qiskit v1.0 จึงระบุไว้ในข้อกำหนด ไม่สามารถย้อนหลังการเปลี่ยนแปลงข้อกำหนดไปยังเวอร์ชันที่ปล่อยแล้วก่อนหน้านี้ได้ และ pip จะค้นหาย้อนหลังไปเรื่อยๆ เพื่อหาสิ่งที่ใช้งานได้เมื่อสร้างสภาพแวดล้อม

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit 0.45 หรือ 0.46

ถ้ามีสภาพแวดล้อมที่เสียหายหลังจากพยายามติดตั้ง Qiskit 0.45 หรือ 0.46 สถานการณ์ที่น่าจะเป็นที่สุดคือ pip ติดตั้ง Qiskit v1.0 เพราะพยายามเลือกเวอร์ชันล่าสุดของแพ็กเกจ แม้ว่าไม่ได้กำหนดไว้ วิธีที่ง่ายที่สุดในการแก้ไขคือสร้าง virtual environment ใหม่ แล้วรันคำสั่ง pip install เพียงครั้งเดียวที่รวมแพ็กเกจทั้งหมดที่ต้องการ พร้อมกับรายการ 'qiskit<1' อย่างชัดเจน ถ้า pip resolve dependency graph นี้ได้สำเร็จ ก็จะได้ virtual environment ที่ใช้งานได้ ถ้า distribution อย่างน้อยหนึ่งตัวต้องการ Qiskit v1.0 หรือมากกว่า pip ควรแสดงข้อความแสดงข้อผิดพลาดที่อธิบายเรื่องนี้ ซึ่งมีลักษณะเหมือนในส่วนที่ว่าด้วย resolution ที่ล้มเหลว

สามารถใช้คำสั่ง pipdeptree ที่ระบุไว้ในสร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit v1.0 จากในสภาพแวดล้อมที่เสียหายเพื่อระบุว่า distribution ใดมีข้อกำหนดชัดเจนบน qiskit>=1

ฉันเป็นนักพัฒนา สภาพแวดล้อมถูกต้องแน่นอน แต่ยังคงพบข้อผิดพลาดอยู่

ก่อนอื่น ต้องมั่นใจ อย่างแน่ชัด ว่าสภาพแวดล้อมถูกต้อง การทดสอบที่ Qiskit ใช้ในการตรวจสอบสภาพแวดล้อมที่เสียหายนั้นค่อนข้างแข็งแกร่ง โดยเฉพาะอย่างยิ่ง มันค้นหาข้อมูล distribution จาก importlib.metadata บนแพ็กเกจที่ติดตั้งและตรวจสอบหมายเลขเวอร์ชันที่ได้รับ ด้านของ Qiskit v1.0 ในการทดสอบยังตรวจสอบไฟล์ sentinel ที่มีอยู่ใน Qiskit เวอร์ชันเก่าแต่ไม่มีใน Qiskit v1.0 ด้วย

ถ้าเป็นนักพัฒนา Qiskit อาจมีไดเรกทอรี qiskit.egg-info หรือ qiskit-terra.egg-info เก่า (หรือ *.dist-info) อยู่บน meta path (ดู sys.meta_path) ที่หลงเหลือจากการติดตั้งแบบ editable เก่าๆ โดยเฉพาะอย่างยิ่ง ให้ตรวจสอบ working directory สำหรับไดเรกทอรี *.egg-info และ *.dist-info ใดๆ ถ้าอยู่ที่รากของ repository ที่ checkout ไว้ ก็สามารถลบทิ้งได้ สิ่งเลวร้ายที่สุดที่อาจเกิดขึ้นคืออาจต้อง pip install -e . อีกครั้ง และแม้กระทั่งนั่นก็ไม่น่าจะเป็นไปได้ เพราะโดยทั่วไปนี่เป็นแค่ส่วนหนึ่งของกระบวนการ build ของ setuptools ที่ไม่ได้รับการทำความสะอาด

ถ้าข้อมูลด้านบนไม่ช่วยและมั่นใจ 100% ว่าสภาพแวดล้อมถูกต้อง (หรือกำลังทดสอบสภาพแวดล้อมที่เสียหายโดยตั้งใจ):

สร้าง issue ใน Qiskit พร้อมอธิบายว่าเกิดขึ้นได้อย่างไรและทำไมถึงแน่ใจว่าสภาพแวดล้อมถูกต้อง เพื่อให้เราแก้ไขได้
สามารถ suppress exception ได้โดยการตั้งค่าตัวแปรสภาพแวดล้อม QISKIT_SUPPRESS_1_0_IMPORT_ERROR=1

แหล่งที่มา: IBM Quantum docs — อัปเดตเมื่อ 10 มิ.ย. 2569

เวอร์ชันภาษาอังกฤษ บน doQumentation — อัปเดตเมื่อ 10 มิ.ย. 2569

การแปลนี้อิงตามเวอร์ชันภาษาอังกฤษวันที่ 11 มี.ค. 2569

สำหรับผู้ใช้​

สร้าง environment ใหม่​

ใช้งาน environment ใหม่​

สำหรับนักพัฒนา​

คำแนะนำสำหรับ requirements​

คำแนะนำสำหรับการทดสอบกับ Qiskit v1.0​

อัพเกรด environment เดิมด้วยตนเอง​

ตัวอย่าง GitHub Actions workflows แบบ manual​

ตัวอย่าง tox configuration​

การแก้ไขปัญหา​

import qiskit แจ้ง "ModuleNotFoundError: No module named 'qiskit'"​

import qiskit สำเร็จ แต่พอลองทำอะไรก็ได้ "AttributeError: module 'qiskit' has no attribute '...'"​

pip ปฏิเสธที่จะติดตั้งบางแพ็กเกจพร้อมกัน​

pip สำเร็จแต่แสดงข้อผิดพลาดหลังรันคำสั่ง pip install​

import qiskit ขึ้น ImportError​

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit v1.0​

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit 0.45 หรือ 0.46​

ฉันเป็นนักพัฒนา สภาพแวดล้อมถูกต้องแน่นอน แต่ยังคงพบข้อผิดพลาดอยู่​

สำหรับผู้ใช้

สร้าง environment ใหม่

ใช้งาน environment ใหม่

สำหรับนักพัฒนา

คำแนะนำสำหรับ requirements

คำแนะนำสำหรับการทดสอบกับ Qiskit v1.0

อัพเกรด environment เดิมด้วยตนเอง

ตัวอย่าง GitHub Actions workflows แบบ manual

ตัวอย่าง `tox` configuration

การแก้ไขปัญหา

`import qiskit` แจ้ง "ModuleNotFoundError: No module named 'qiskit'"

`import qiskit` สำเร็จ แต่พอลองทำอะไรก็ได้ "AttributeError: module 'qiskit' has no attribute '...'"

`pip` ปฏิเสธที่จะติดตั้งบางแพ็กเกจพร้อมกัน

`pip` สำเร็จแต่แสดงข้อผิดพลาดหลังรันคำสั่ง `pip install`

`import qiskit` ขึ้น `ImportError`

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit v1.0

สร้างสภาพแวดล้อมที่ใช้งานได้สำหรับ Qiskit 0.45 หรือ 0.46

ฉันเป็นนักพัฒนา สภาพแวดล้อมถูกต้องแน่นอน แต่ยังคงพบข้อผิดพลาดอยู่