Installation

Before we begin, we need to install Python on our own computer. Current versions of Python, along with further installation instructions for different operating systems, are available at https://python.org. For the example code in this tutorial, we recommend Python version 3.12.8. Other models may require a different versions of Python. Before you start, make sure that all packages run in the required versions.

After installing Python, we (1) create a project folder and (2) a virtual Python environment, into which we then (3) install all required packages. Creating a virtual environment is not strictly necessary, but we recommend this step to avoid conflicts between different software versions. Finally, we (4) open the Jupyter Notebook environment, in which we can try out the examples from this tutorial.

Models provided on Hugging Face can be loaded and applied to text in just a few lines of Python code. The models presented in this tutorial require at least 10GB of free disk space and enough memory (RAM or VRAM; at least 8GB, more is better). Note: beyond the models presented here, there are also much larger models that require significantly more disk space and cannot be run on typical consumer hardware (laptop or desktop). These are not necessary for most use cases in content analysis, however. All three models used in this tutorial are small enough to run comfortably on a laptop CPU — no GPU required, though a GPU will make the generative model noticeably faster. Before using other models on Hugging Face, always check their hardware requirements, which can be roughly estimated from the model size.

No problem! Explanations for the individual steps of the code are hidden behind the numbers on the right. Simply hover your mouse over the number to see the explanation. Where the respective code is executed (in Python, R, or the terminal) is shown in the header of the code block.

Python
print("Hello! 👋")
1
This is a simple Python command that prints the text “Hello” to the console. The output appears below the code block. 
Hello! 👋

If you run into problems during the installation, you can also try out the examples in this tutorial without installing anything on your own computer. Google Colab provides a free cloud-based Jupyter Notebook environment, which allows you to run the code directly in your web browser without any installation. However, please note that Colab has some limitations, such as limited runtime and available resources. Also, please check if you can (and are allowed to) upload your data to Colab. If you want to use your own data, we recommend installing Python and the required packages on your own computer.

1 Create a project folder

We can create the project folder using the file manager (Windows) or Finder (Mac). We then navigate to our project folder and open our computer’s command line there:

Right-click on the project folder in Finder and select “New Terminal at Folder”.

Shift + right-click on the project folder in Explorer and select “Open PowerShell window here”.

2 Create a virtual Python environment

In the command line, we run the following command, which creates the virtual Python environment:

Terminal
python3.12 -m venv env
1
We create a virtual Python environment named env. The name of the virtual environment can be chosen freely, but ideally should not contain spaces or special characters.

The following command activates the virtual environment. We need to run this second command every time we want to work in the virtual Python environment:

Terminal
source env/bin/activate
1
We activate the virtual Python environment named env. The name of the virtual environment must match the name we chose in the previous step. 
Terminal
.\env\Scripts\activate
1
We activate the virtual Python environment named env. The name of the virtual environment must match the name we chose in the previous step.

If PowerShell blocks the execution of scripts, this can be changed with the following command:

Terminal
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
2
We allow the execution of scripts in the current PowerShell session. This is necessary to activate the virtual Python environment. This setting only applies to the current session and is reset when PowerShell is closed.

3 Install packages

Next, we can install the required packages: the transformers library from Hugging Face (Wolf et al., 2020), the pandas library for data handling (McKinney, 2010), as well as accelerate, which transformers uses in the background to run models efficiently. Depending on the transformer model used, we may need additional packages, which corresponding error messages will point out along the way. These can then also be installed via pip install [package-name]. For the examples in this tutorial, we need the packages installed in the following code:

Terminal
pip install jupyter pandas transformers torch accelerate
1
We install the required packages in the virtual Python environment. This may take a few minutes.
TipPackage versions for the examples presented

The examples presented in this tutorial were tested with the following package versions. It is possible that newer versions of the packages will be released in the future that may no longer be compatible with the example code. In this case, you can install the versions of the packages listed below specifically, by specifying the respective package name with == and the version number. For example: pip install transformers==4.55.1.

accelerate==1.10.0
jupyter==1.1.1
pandas==2.3.1
torch==2.8.0
transformers==4.55.1

4 Open Jupyter Notebook

Finally, with the following command we can open the Jupyter Notebook environment in which we can try out the examples from this tutorial. In the Jupyter Notebook environment, we can then run the Python scripts described in the following chapters. These example notebooks (.ipynb) can be downloaded from the respective tutorial page and then placed in the project folder. Alternatively, we can also create a new notebook (see below).

Terminal
jupyter notebook
1
We open the Jupyter Notebook environment. This opens a new window in our web browser, in which we can see the Jupyter Notebook environment.

Instead of the example notebooks, we can also create a new notebook by clicking “File” in the Jupyter dashboard, then “New”, and then selecting “Notebook”. This creates a new notebook file in which we can write and run our Python code. When we open the notebook, we are first asked how we want to run the code. We select “Python 3 (ipykernel)” here, to make sure we use the Python version we installed earlier.

In the Jupyter Notebook, we can then run the individual cells by clicking the “Run” button or using the keyboard shortcut Shift + Enter. The results of the execution are displayed directly below the respective cell.

References

McKinney, W. (2010). Data structures for statistical computing in python. 56–61. https://doi.org/10/ggr6q3
Wolf, T., Debut, L., Sanh, V., Chaumond, J., Delangue, C., Moi, A., Cistac, P., Rault, T., Louf, R., Funtowicz, M., Davison, J., Shleifer, S., von Platen, P., Ma, C., Jernite, Y., Plu, J., Xu, C., Scao, T. L., Gugger, S., … Rush, A. M. (2020, July 13). HuggingFace’s transformers: State-of-the-art natural language processing. https://doi.org/10.48550/arXiv.1910.03771