Installation#
This page explains how to install vak
.
The library can be installed with the package managers conda
or pip
.
We recommend conda
for most users. For more detail, please see Why do we recommend conda?.
We also recommend installing vak
into a virtual environment.
For an explanation, please see Why use a virtual environment?.
Prerequisites#
A package manager#
First you need a package manager, that can install vak
and the other software libraries
that it depends on. For example, the conda
package manager that is installed for you
with the Anaconda distribution (https://docs.anaconda.com/anaconda/install/).
If you prefer, you can also install vak
with
the Python package manager pip
(https://pip.pypa.io/en/stable/getting-started/).
A terminal program#
You will also need to use a terminal program to run vak
through its command-line interface, as shown below:
On macOS, you can use the built-in
Terminal application
or alternatives like iTerm2.
If you install Anaconda, then conda
will be available to you through the terminal.
The built-in terminal will also work on Linux.
If you are on Windows and using Anaconda and the conda
package manager,
you will want to install and run vak
through the Anaconda prompt,
that can be accessed as shown in the video below.
(on Linux) the libsndfile
library#
We use soundfile to read audio data,
which relies on libsndfile
.
On Windows and macOS, libsndfile
will be automatically installed.
On Linux, you need to install the library manually. For example, on Ubuntu run:
sudo apt-get install libsndfile1
Commands to install vak
#
with conda
#
To create a new virtual environment that contains vak
and all the libraries it depends on, open your terminal and run:
conda create --name vak-env python=3.8 vak -c pytorch -c conda-forge
Notice that we specify the Python version and the vak
version.
This makes the install faster because the package manager has to do less work.
You can specify newer versions of Python,
and you should specify the latest version of vak
.
Notice also that you need to make
sure the pytorch channel is specified first
(by writing -c pytorch
before -c conda-forge
),
because vak
is built on top of pytorch
and torchvision
,
and you want their channel to take precedence
for installing those two libraries.
To install vak
into an existing environment, run:
conda install vak -c pytorch -c conda-forge
Again you should specify the latest version of vak
,
and make sure the pytorch channel is specified first,
so that it takes precedence.
Troubleshooting conda
installations on Windows#
If you encounter cryptic errors like on Windows,
like a WinError
or a BrokenPipeError
,
it may help to create a new conda
environment,
and first install pytorch
and torchvision
according to the instructions on pytorch.org,
before installing vak
. For example:
C:\You> conda create -n vak-env python==3.8
C:\You> conda activate vak-env
(vak-env) C:\You> pip install torch===1.10.2 torchvision===0.11.3 -f https://download.pytorch.org/whl/torch_stable.html
(vak-env) C:\You> pip install vak
(vak-env) C:\You> pip install tweetynet
(but again make sure you are installing the latest versions – the numbers above may be out of date).
with pip
#
To install vak
with pip
, run:
pip install vak
Installing a neural network model#
Finally you’ll want to install a neural network model to train!
vak
was developed to benchmark a neural network model,
TweetyNet.
We use this model in the tutorial: Automated Annotation.
With conda
#
conda install tweetynet -c conda-forge
With pip
#
(You can use pip
inside a conda
environment.)
pip install tweetynet
Getting help#
If you need help or have questions about installation,
please create a new topic in the
VocalPy forum,
using the “Q&A” category and adding the vak
tag.
Why do we recommend conda
?#
Many libraries for data science packages have dependencies
written in languages besides Python. There are platforms
dedicated to managing these dependencies that you may find it easier to use.
For example, Anaconda (https://www.anaconda.com/download) (which is free).
You can use the conda
command-line tool that they develop
to create environments and install the libraries that this package
depends on. Here is an in-depth look at using conda
to manage environments:
https://www.freecodecamp.org/news/why-you-need-python-environments-and-how-to-manage-them-with-conda-85f155f4353c/.
Further detail about conda
and how it relates to other tools like
virtualenv
and pip
can be found in this blog post:
https://jakevdp.github.io/blog/2016/08/25/conda-myths-and-misconceptions/.
vak
depends on several widely-used libraries from the Python data science ecosystem.
Currently, the easiest way to install these libraries across operating systems
(Linux, Mac, and Windows) is to use the conda
tool.
It will help you create what is a called a “virtual environment”,
and then install the libraries that vak
depends on into that environment.
The easiest way to use conda
is to install the
Anaconda platform (https://www.anaconda.com/download) (which is free).
The main reason we use conda
to install other dependencies,
instead of letting pip
handle that,
is because conda
makes it easier to work with GPUs.
For example, using conda
avoids the need to install and configure drivers for NVIDIA.
In contrast, if you install just with pip
, and you are using a GPU,
you may need to ensure that the installation of PyTorch
is using the system install of binaries
that it depends on, such as libcuda.so
.
conda
makes it possible to install cudatoolkit
and other dependencies into a virtual environment
to avoid dealing with system-wide installs of binaries.
Why use a virtual environment?#
Virtual environments makes it possible to install the software libraries that a program depends on, known as “dependencies”, so that they can be isolated from the dependencies of other programs. This avoids many issues, like when two programs depend on two different versions of the same library. For an in-depth explanation of virtual environments, please see this guide from the Turing Way. For a Python specific guide, see https://realpython.com/python-virtual-environments-a-primer/ or https://dev.to/bowmanjd/python-tools-for-managing-virtual-environments-3bko.