Password Hashing with `passlib` vs. Django

1. The Importance of Password Hashing

Before we write any code, it's essential to be clear on why we're doing this. Storing user passwords in plain text is a critical security vulnerability. If your database were ever compromised, an attacker would have direct access to every user's credentials.

The solution is hashing: a one-way cryptographic process that transforms a password into a fixed-length string of characters, called a hash. This process is irreversible, meaning you cannot get the original password back from its hash.

To understand this core concept, please watch the first minute of this video.

2. Password Hashing with passlib

passlib is a comprehensive password hashing library for Python. It provides a convenient object, CryptContext, which manages the hashing algorithms and the verification process for us.

Installation

To get started, you need to install passlib along with a library for a specific hashing algorithm. We'll use bcrypt, which is a strong and widely trusted choice.

pip install "passlib[bcrypt]"

This command installs both passlib and the bcrypt library.

Configuration and Hashing

The process involves two main steps:

1. Create a CryptContext instance and tell it which hashing algorithm to use.
2. Use the hash() method of this context object to hash a new user's password.

The following video demonstrates this process clearly. It will guide you through creating the context and then integrating the hashing logic into a user creation endpoint.

As you saw in the video, the core logic looks like this:

from passlib.context import CryptContext




# 1. Create the CryptContext instance
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")




# 2. Define a function to hash a password
def hash_password(password: str):
    return pwd_context.hash(password)




# In your user creation logic:
# new_user.password = hash_password(form_data.password)
# db.add(new_user)
# db.commit()

Verification

Hashing is for storing passwords. Verification is for checking them at login. The CryptContext object also provides a verify() method for this. It takes two arguments: the plain-text password submitted by the user and the hashed password retrieved from your database.

This next video segment demonstrates the verification step.

So, a verification function would look like this:

def verify_password(plain_password: str, hashed_password: str):
    return pwd_context.verify(plain_password, hashed_password)




# In your login logic:
# user = get_user_from_db(username)
# if not user or not verify_password(submitted_password, user.hashed_password):
#     raise HTTPException(status_code=401, detail="Incorrect username or password")
# 
# # If verification succeeds, create a token

3. A Quick Note on Code Structure

Your goal is to build professional applications, so organizing your code is important. As shown in the first video, it's good practice to move your hashing logic into a separate utility file, for example, app/security.py or app/utils.py.

A more advanced, object-oriented approach is to use a class or mixin, which keeps the hashing and verification methods neatly bundled.

4. The Modern Way: pwdlib

While passlib is powerful and widely used, it is no longer actively maintained. This can lead to deprecation warnings and potential future incompatibilities. Because of this, the official FastAPI documentation has been updated to recommend a new library: pwdlib.

For your professional development, it's crucial to be aware of this and use the most current, supported tools.

Using pwdlib is conceptually identical to passlib, but with a slightly simpler API.

Installation:

pip install "pwdlib[bcrypt]"

Usage:

from pwdlib import PasswordHash




# The context is created implicitly
password_hash = PasswordHash.recommended()




# Hashing
def hash_password(password: str) -> str:
    return password_hash.hash(password)




# Verification
def verify_password(plain_password: str, hashed_password: str) -> bool:
    return password_hash.verify(plain_password, hashed_password)

The PasswordHash.recommended() constructor automatically selects a strong, modern algorithm (like Argon2 if available, falling back to bcrypt), simplifying configuration. For any new project you start, pwdlib is the recommended choice.

5. Comparison: FastAPI vs. Django Hashing

Let's draw a direct comparison to solidify your understanding:

In essence, FastAPI gives you more control and responsibility, whereas Django provides a more "batteries-included," abstracted experience.

Conclusion

In this lesson, you've learned how to securely handle user passwords in a FastAPI application, a critical first step in building a robust authentication system.

Key Takeaways:

• Never store plain-text passwords. Always use a strong, one-way hashing algorithm like bcrypt or Argon2.
• The classic way to handle hashing in FastAPI is with passlib, using a CryptContext object to .hash() and .verify() passwords.
• The modern, officially recommended library is pwdlib, which provides a simpler API (PasswordHash.recommended()) and is actively maintained.
• Unlike Django's highly-abstracted auth system, FastAPI requires you to explicitly call hashing and verification functions in your application logic.

Preview of the Next Lesson:

Now that we can confidently verify a user's password, what's next? We need a way to keep them "logged in" for subsequent requests without sending their password every time. In our next lesson, we will create and decode JWT access tokens for stateless authentication. You'll learn how to generate a secure token upon successful login, which the user can then provide to access protected endpoints.