Dev Setup

Important

ESPnet3 development is moving to a Pixi-based workflow. New contributor setup should start from Pixi instead of conda.

Why Pixi

ESPnet3 development is moving to a Pixi-based workflow.

Pixi is a good base for ESPnet3 because it can:

• replace conda for Python and non-Python dependencies
• install tools such as ffmpeg and cmake in the same environment
• work well with uv for fast Python package installs

If you install Pixi, you usually do not need a separate conda setup.

Note

Pixi handles Python and non-Python dependencies together, while uv gives fast Python package installs inside that environment.

Install Pixi

Install Pixi first:

curl -fsSL https://pixi.sh/install.sh | bash

Open a new shell after the install, or reload your shell config.

Create a development environment

Clone ESPnet and move into the repository:

git clone https://github.com/espnet/espnet.git
cd espnet

Create a Pixi environment with Python and common system tools:

pixi init
pixi add python=3.11 pip ffmpeg

If your recipe needs extra system packages, add them in the same way:

pixi add sox cmake

Then enter the environment:

pixi shell

If you want to enter the shell from shell script, you can write:

eval "$(pixi shell-hook)"

Install ESPnet3 for development

Inside the Pixi shell, install ESPnet from source:

uv pip install -e .

Add more extras if needed:

uv pip install -e ".[asr,tts]"
uv pip install -e ".[enh]"

This keeps Python package installation fast while Pixi manages the base environment.

If something goes wrong

If the installation does not behave as expected, explicitly passing the Python interpreter often fixes it:

uv pip install -e . --python $(which python)

Install extra Python packages

For extra Python packages, use uv inside the Pixi shell. For example:

uv pip install lightning transformers gradio

If you need a package from a local checkout:

uv pip install -e /path/to/package

Install non-Python dependencies

Use pixi add for tools that are not Python packages. Package names follow conda-forge naming, not apt or brew:

pixi add ffmpeg cmake sox

You can check that they are available from the Pixi environment:

pixi shell
ffmpeg -version
cmake --version

This is the preferred way to install common recipe dependencies.

Optional recipe tool installers

Some recipes still need extra installers from tools/installers/. Use them after entering the Pixi shell:

cd tools
./installers/<installer>.sh

Examples:

• install_ffmpeg.sh
• install_k2.sh
• install_warp-transducer.sh

Check the script before running it.

Warning

Most installers call pip directly rather than uv, which can be slower and may install packages into an unexpected environment. If you hit issues, replace the pip install calls inside the script with uv pip install for faster, more predictable installs.

Verify the setup

python -c "import espnet3"
python -c "from espnet3.systems.asr.system import ASRSystem"
ffmpeg -version

Run tests

pytest test/espnet3/

Run a smaller test target when possible:

pytest test/espnet3/systems/asr/

Troubleshooting

• pixi: command not found: restart your shell after installing Pixi.
• uv: command not found: add uv with pixi add uv, then reopen pixi shell.
• CUDA or PyTorch mismatch: reinstall the correct PyTorch build inside the Pixi environment.
• Missing recipe dependency: check tools/installers/ and the recipe README.

If the environment still fails, include these in your issue:

• the pixi add command you used
• the uv pip install command you used
• python --version
• the full traceback