インストールガイド

インストールガイド#

このガイドを読むと、haniwers を簡単にインストールできます。あなたの環境に合わせた方法を選んでください。

クイックスタート（初心者向け推奨）#

もっとも簡単な方法は uv run --with です。インストール不要で即座に実行できます：

# インストール不要！ こちらのコマンドで即座に実行
uv run --with haniwers==0.24.2 haniwers version

# 測定開始
uv run --with haniwers==0.24.2 haniwers daq

これだけです！ uvがあれば、すぐにhaniwersを使い始められます。

uvがない場合

uvをまだインストールしていない場合は、下の「1. uvでインストール」を読んでください。 または、「2. pipxでインストール」でpipxをインストールして使用することもできます。

インストール方法の比較#

3 つのインストール方法があります。 あなたの用途に合わせて選んでください。

方法

難易度

推奨ユーザー

特徴

uv

⭐ 簡単

新しいツールを試したい人

最新、高速、推奨

pipx

⭐ 簡単

ツールとして使いたい人

安定、シンプル、依存関係の分離

pip + 仮想環境

⭐⭐ 中程度

開発者、複数プロジェクト管理

標準的、安全

Poetry

⭐⭐⭐ 難しい

開発に参加したい人

完全な開発環境

1. uv でインストール（最新推奨）#

メリット： 最も高速、最も新しい、開発が盛ん

uvのインストール#

# Homebrewで uv をインストール（macOS）
brew install uv

# または、pipでインストール
pip install uv

# パスの確認
uv --version

haniwers の実行方法#

方法 A: インストール不要（推奨）#

# インストール不要で即座に実行
uv run --with haniwers==0.24.2 haniwers version

方法 B: ツールとしてインストール#

# uv tool でインストール
uv tool install haniwers

# バージョン確認
uvx haniwers version

アップデート#

uv tool upgrade haniwers

アンインストール#

uv tool uninstall haniwers

2. pipx でインストール（初心者向け推奨）#

メリット： シンプル、どこからでも使える、依存関係の分離

pipx のインストール#

pipx をまだインストールしていない場合：

# macOS（Homebrewおすすめ）
brew install pipx

# Linux
pip3 install --user pipx
export PATH=$PATH:~/.local/bin

# Windows（WSL推奨）
pip install pipx

haniwers のインストール#

# haniwers をインストール
pipx install haniwers

# バージョン確認
haniwers version

アップデート#

pipx upgrade haniwers

アンインストール#

pipx uninstall haniwers

使用方法#

インストール後は、どのディレクトリからでも使用できます：

# どこからでも実行可能
haniwers daq --help
haniwers version
haniwers ports

3. pip + 仮想環境でインストール（開発者向け）#

メリット： 複数プロジェクトを管理できる、カスタマイズ可能

インストール手順#

# 1. 作業用ディレクトリを作成
mkdir ~/haniwers-workspace
cd ~/haniwers-workspace

# 2. 仮想環境を作成
python3 -m venv .venv

# 3. 仮想環境を有効化
source .venv/bin/activate

# 4. haniwers をインストール
pip install haniwers

# 5. バージョン確認
haniwers version

Windows の場合：

# 仮想環境を有効化（Windows）
.venv\Scripts\activate

# 以降は同じ
pip install haniwers

仮想環境の有効化（毎回必要）#

# macOS / Linux
cd ~/haniwers-workspace
source .venv/bin/activate

# Windows
cd ~/haniwers-workspace
.venv\Scripts\activate

有効化されると、プロンプトが以下のように変わります：

(.venv) $

アップデート#

(.venv) $ pip install -U haniwers

アンインストール#

(.venv) $ pip uninstall haniwers

複数の Python バージョン#

特定の Python バージョンで使いたい場合：

# Python 3.11 で仮想環境を作成
python3.11 -m venv .venv

4. 開発環境のセットアップ（開発者向け）#

メリット： 最新コード、テスト実行、コード変更可能

前提条件#

  • Git

  • Python 3.9 以上

  • Poetry

インストール手順#

# 1. リポジトリをクローン
git clone https://gitlab.com/qumasan/haniwers.git
cd haniwers

# 2. Poetry で依存関係をインストール
poetry install

# 3. バージョン確認
poetry run haniwers version

開発時のコマンド#

# haniwers を実行
poetry run haniwers daq --help

# テストを実行
poetry run pytest

# コードをフォーマット
poetry run ruff format

# 型チェック
poetry run mypy haniwers

詳細は 開発ガイド を参照してください。

トラブルシューティング#

問題：「haniwers: command not found」#

解決方法：

インストール確認：

# pipx の場合
pipx list

# pip + 仮想環境の場合
source .venv/bin/activate
which haniwers

# uv の場合
uv tool list

問題：「Permission denied」エラー#

解決方法： sudo は使わず、pipx または仮想環境を使います：

# 推奨: pipx を使用
pipx install haniwers

# または仮想環境を作成
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers

問題：Python のバージョンが古い#

確認方法：

python3 --version
# Python 3.9 以上が必要

解決方法：

# macOS（Homebrew）
brew install python@3.11

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.11

# その後、指定したバージョンで仮想環境を作成
python3.11 -m venv .venv
source .venv/bin/activate
pip install haniwers

問題：Windows で動作しない#

解決方法： Windows Subsystem for Linux（WSL）の使用を推奨します：

# WSL で実行
wsl

# Linux コマンドを使用
sudo apt-get update
sudo apt-get install python3 python3-pip
pip install pipx
pipx install haniwers

システム要件#

項目

要件

OS

Linux, macOS, Windows（WSL推奨）

Python

3.9 以上

インターネット

インストール時に必要

ディスク

約 100 MB

プラットフォーム別の注意事項#

macOS#

Apple Silicon（M1/M2）の場合：

# Homebrew で Python をインストール（推奨）
brew install python@3.11

# または uv を使用（自動的に対応）
brew install uv
uv tool install haniwers

Intel Mac の場合：

brew install python@3.11
pipx install haniwers

Linux（Ubuntu/Debian）#

# 必要なパッケージをインストール
sudo apt-get update
sudo apt-get install python3 python3-pip

# pipx をインストール
pip3 install --user pipx

# パスを設定
export PATH=$PATH:~/.local/bin

# haniwers をインストール
pipx install haniwers

Windows#

WSL を推奨しますが、ネイティブ Windows でも動作します：

# Python 3.11 をインストール
# https://www.python.org からダウンロード

# コマンドプロンプトまたは PowerShell で実行
python -m pip install pipx
pipx install haniwers

インストール確認#

インストール後、以下のコマンドで正常に動作確認できます：

# バージョン確認
haniwers version

# 利用可能なコマンド確認
haniwers --help

# ポート確認（検出器接続確認）
haniwers ports

すべてのコマンドが実行できれば、インストール完了です！🎉

次のステップ#

インストール後に進むステップ：

  1. セットアップ - 検出器接続の設定

  2. ワークフロー - 最初の測定を実行

  3. コマンドリファレンス - 利用可能なコマンド確認

よくある質問（FAQ）#

Q: uv、pipx、pip どれを使えばいい？#

A: 初心者なら uv または pipx を推奨します。開発に参加する場合は Poetry を使用してください。

Q: アンインストールしたい場合は？#

A: インストール方法に応じて：

# uv の場合
uv tool uninstall haniwers

# pipx の場合
pipx uninstall haniwers

# pip + 仮想環境の場合
pip uninstall haniwers

Q: 最新版に更新したい場合は？#

A: インストール方法に応じて：

# uv の場合
uv tool upgrade haniwers

# pipx の場合
pipx upgrade haniwers

# pip + 仮想環境の場合
pip install -U haniwers

Q: 複数のバージョンを同時に使いたい場合は？#

A: 複数の仮想環境を作成してください：

# バージョン 0.23
mkdir ~/workspace-v023
cd ~/workspace-v023
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers==0.23.1

# バージョン 0.22
mkdir ~/workspace-v022
cd ~/workspace-v022
python3 -m venv .venv
source .venv/bin/activate
pip install haniwers==0.22.0

サポート#

問題が発生した場合：

  1. トラブルシューティング セクションを確認

  2. よくある質問 を確認

  3. Issues を確認または作成

目次