KeePassXC for Mac OS X - Secure password manager

Updated 12 March 2019

Table of Contents

...Loading Table of Contents...

    KeePassXC is a cross-platform, free and open source (FOSS) password manager that allows you to store all of your passphrases in one secure, portable database.

    Required reading

    What you will get from this guide

    • The ability to save all of your passphrases in one encrypted database
    • The ability to copy and paste those passphrases so you do not have to memorise them
    • The ability to generate completely random passphrases
    • The ability to encrypt notes and files attached to the entries in your password database

    1. Introduction to KeePassXC

    KeePassXC is a tool that helps you store and manage various passphrases inside an encrypted database file. This file is encrypted to a master passphrase that you create. KeePassXC can also generate strong passphrases for your accounts.

    Because this database is encrypted, you can store copies in various places, which makes backup relatively easy. We do not recommend sending your database by email or storing it online where it might be accessed by others, but many KeePassXC users keep a copy on their primary computer, a copy on a USB memory stick and a copy on their backup drive.

    In the sections that follow, you will learn how to:

    • Create password database and set a master passphrase
    • Save your newly created password database
    • Generate a random password for a particular service or account
    • Extract passwords from KeePassXC when you need them
    • Change your master passphrase

    1.0. Things you should know about KeePassXC before you start

    If you use KeePassXC consistently for a particular account or passphrase, you may not need to remember that passphrase at all. In fact, you never even need to see it. You can simply copy it from KeePassXC and paste it into the login or password screen. (KeePassXC will wipe it from your clipboard memory when you're done.) Furthermore, the random passphrases that KeePassXC generates are typically much stronger than the ones we come up with ourselves.

    1.1. Other tools like KeePassXC

    KeePassXC is available for GNU Linux, Windows and Mac OS X. Similar tools include:

    • KeePass2Android: Free and open-source software for Android. Its database format is compatible with KeePassXC.
    • MiniKeePass: Free and open-source software for iPhone. Its database format is compatible with KeePassXC.
    • 1Password: a commercial product available for Mac OS X, Microsoft Windows, iPhone and iPad.

    2. Install and launch KeePassXC

    To download and install KeePassXC, follow the steps below:

    Step 1. Visit the KeePassXC download site:

    Figure 1: KeePassXC download page

    Step 2. Click on the Binary bundle for macOS 10.10 and later link to download KeePassXC.

    Step 3. Save it to Downloads folder.

    Figure 2: Saved KeePassXC .dmg file in Downloads folder

    Step 4. In the Finder window, find the downloaded file and double click to mount it as a disk image. It will show up under Devices in the sidebar of the Finder window.

    Note: In this guide, we'll be installing KeePassXC in the Applications folder of the desktop. But remember that you can also install and use it on portable media, such as a USB flash memory stick or external disk drive. If you choose install it on a USB flash memory stick, you will be able to launch the application using other computers with compatible operating systems. (Since it is a cross-platform tool, you can also save a version of KeePassXC for each operating system on your USB drive along with your personal database, enabling you to open and use your database on any other computer.)

    Figure 3: Drag the KeePassXC app into Applications folder

    Step 5. Drag the KeePassXC icon into the Applications folder.

    Step 6. Before we start using KeePassXC, we should unmount (or 'eject') the KeePassXC disk image. Find KeePassXC under Devices in the Finder sidebar. Click on the {eject} icon next to it in the sidebar to unmount the disk image.

    Step 7. Click on Applications folder on left side of Finder window and find KeePassXC

    Figure 4: KeePassXC in Applications folder

    Step 8. Double click on KeePassXC to lounch it.

    Figure 5: Confirm that you want to lounch KeePassXC

    Step 9. Confirm that you want to open it by clicking on Open button.

    3. Create and save a new KeePassXC database

    After launching KeePassXC, follow the steps below to create and save a password database.

    Figure 1: KeePassXC with no database open

    Step 1. Click Create new database in the KeePassXC window.

    KeePassXC will activate a windows so you can choose a location for your new password database and give it a name.

    Figure 2: Choosing a name and location for your password database

    Step 2. Navigate to the location where you want to save your database

    In this example, we will save our KeePassXC database on the Desktop, but you can put it anywhere. If you store it on a USB flash memory stick along with a copy of the KeePassXC application, for example, you will be able to access and use your database from other computers. (As long as you trust those computers not to be infected by malware!)

    Step 3. Type a filename into the Save As box

    Tip: In this example, we name our database my-database.kdbx, but you can name it anything you like. If you are worried that someone with access to your computer might see this file and demand that you give them your master passphrase, you might want to come up with something less conspicuous. If you add a different "extension" to the end off the filename, for example, your operating system will usually give it a more "normal looking" icon. You could name your password database "Recipes.docx," for example, or "Rental Agreement.pdf". But keep in mind that if you give your password database a name that does not end in ".kdbx", you will not be able to double-click the file to open it in KeePassXC. You will have to launch KeePassXC first, then open your database using the menu. Luckily, KeePassXC remembers the last database you opened, so you won't have to do this often.

    Figure 3: Choosing a name and location for your password database

    Step 4. Click [Save]

    Important: Your master passphrase will be used to encrypt your password database. This is how KeePassXC protects all of the other passphrases it stores, so it is extremely important that you choose a strong master passphrase and that you not use it anywhere else. Unfortunately, this passphrase must also be memorable. (You obviously can't keep your KeePassXC master passphrase inside KeePassXC, but writing it down might defeat the purpose of using an encrypted database in the first place. And if you forget it, you will lose access to everything in your database.) So take your time and come up with something strong and memorable. For more advice, see the Create and maintain secure passwords guide.

    Figure 4: Choosing a passphrase for your KeePassXC password database

    Step 5. Choose a strong, memorable master passphrase and type it into the Enter password and Repeat password fields.

    Note: If you want to check your master passphrase (assuming nobody else can see your screen), click the button. To hide your passphrase, click the same button again.

    Step 6. Click [OK].

    Figure 5: A new, empty, saved KeePassXC password database

    This will create and automatically save your KeePassXC database. Now make sure you can find and re-open it using your master passphrase before you start adding entries to it.

    Step 7. Click Database and Select Close database from the KeePassXC menu

    Figure 6: Closing a KeePassXC database

    Now find and re-open your KeePassXC database using your master password.

    Step 8. Click Database and Select Open database from the KeePassXC menu

    Figure 7: Opening a KeePassXC database

    KeePassXC will activate a file browser so you can locate your password database.

    Figure 8: Locating your KeePassXC database

    Step 9. Navigate to the location where you saved your database and click the file.

    Step 10. Click [Open]

    Figure 9: Entering your master passphrase

    Step 11. Type the master passphrase for this KeePassXC password database.

    Step 12. Click [OK]

    Figure 10: Re-opened, empty password database

    Tip: If you were unable to open your database because you forgot the master passphrase, you will have to generate a new one. There is no way to recover a lost passphrase.

    4. Create and manage password entries

    4.1 Create a new group if needed

    Follow the steps below to create a new Group. In this example, we will create a group called "Email".

    Step 1. To create a new group entry, click [Groups > Add new group] from the KeePassXC menu.

    Figure 1: Creating a new group in KeePassXC

    Step 2. Type the name of your group in the Name box.

    Figure 2: Naming a new group in KeePassXC

    Step 3. Click [OK].

    4.2. Create a new password entry

    Follow the steps below to create a new entry in your KeePassXC password database.

    Step 4. Make sure the correct Group is selected.

    Figure 1: Selecting a group for your new entry

    Step 5. Click the button.

    Figure 2: The Add Entry screen

    The Add Entry screen allows you to store information about a particular account or passphrase inside your KeePassXC database. Most of this information is optional.

    Key elements include:

    • Title: A name to describe this particular entry.
    • Password: Your passphrase for this account. You can enter a passphrase manually or click the button next to the Repeat field to generate a random passphrase. (See the following section for more about the Password Generator.) You can make your passphrase visible by clicking the button with the button just to the right of the Password field.)
    • Repeat: Confirm that you have entered the correct passphrase by typing it a second time.

    Optional elements include:

    • Username: The username associated with this entry.
    • URL: The website associated with the password entry.
    • Expires: You can add a reminder for yourself to change the password at a specific time (every six months, for example) by clicking the Expires box.
    • Notes: Here you can enter general notes about the entry. Examples might include server configuration information, links to privacy policies, chosen "security questions," etc. Your comments will be encrypted, along with your passwords, when you close the database. While the entry is open, however, your notes will be visible to anyone who can see your screen.

    You can change the icon for this entry or add an attachment (which will be encrypted along with everything else) by selecting the corresponding category in the left-most column.

    Note: Creating or modifying the password entries in KeePassXC does not change the passwords on your actual account! Think of KeePassXC as a secure electronic sheet of paper for your passwords. It only stores what you write in it, nothing more.

    Step 6. Type the relevant information for the account or passphrase you want to store in your KeePassXC database.

    Figure 3: Filling out the Add Entry form

    Note: If you’d like to generate a new, random passphrase for this entry using KeePassXC’s Password Generator, see the following section.

    Step 7. Click [OK].

    Figure 4: New entry created but not yet saved

    Important: Notice the asterisk (*) after my-database.kdbx in the title bar. This means you have made changes to your database but have not yet saved them. As with any electronic documents, you must save your password database whenever you update it. Otherwise your changes will be lost.

    Step 8. Click the button to save your password database.

    4.3 Generating random passphrases

    It is possible to create a strong passphrase yourself, but it is difficult. And it is especially difficult if you expect your passphrase to be memorable. It is much easier to generate a long, complex and completely random passphrase that is nearly impossible to remember but guaranteed to be strong. KeePassXC provides a Password Generator to help with this process. If you are willing and able to rely on KeePassXC every time you need to enter a particular passphrase, you should consider adopting this strategy.

    You can generate a random passphrase while creating a new entry or while editing an existing entry. To do so, follow the steps below when you get to the Add entry or Edit entry screens.

    Figure 1: Editing or creating an entry

    Step 1. Click the button next to the Repeat box.

    Figure 2: The KeePassXC Random Password Generator

    The KeePassXC Password Generator allows you to specify the length of your passphrase and the types of characters from which it will be created. We will stick with the defaults in this example, so our random passphrase will be 16 characters long and will contain upper-and lower-case letters and numbers.

    Tip: As long as nobody else can see your screen, you can view the randomly generated passphrase by clicking the button to the right of the second Password box. (The one that contains a hidden passphrase.) Clicking the same button again will hide your passphrase.

    Step 2. Click [Apply].

    KeePassXC will automatically enter the randomly generated passphrase into the Password and Repeat fields. If this entry already contained a passphrase, it will be replaced by the new one when you click OK.

    Figure 3: A KeePassXC entry with a randomly generated passphrase

    Step 3. Click [OK].

    Figure 4: A new or edited entry with a randomly generated passphrase

    Step 4. Save your KeePassXC database.

    4.4. Editing an existing password entry

    You can edit existing entries to change your password or modify other details. If nothing else, you should change your passwords periodically.

    Important: If you rely on KeePassXC to record your passphrase for a particular account – rather than memorising it – don't forget to sign in to your account before generating a new passphrase in KeePassXC. Otherwise, you might replace the passphrase in your KeePassXC entry, save your database, and find that you can no longer sign in to your account. If this happens to you, there is a History screen, for each password entry. (It is shown on the left-hand side of Figure 3, below.) You can use this feature to access previous passphrases for this entry.

    To edit an entry, follow the steps below:

    Step 1. Select the group from the list on the left-hand side of the window to see the entries in that group.

    Figure 1: Choosing a group in the main KeePassXC database window

    Step 2. Ctrl-click the chosen entry and select View/Edit entry.

    Figure 2: Selecting a KeePassXC entry to view or edit

    This will open the selected entry for editing.

    Figure 3: Viewing or editing a KeePassXC entry

    With an open entry, you can add new information or edit existing information, including the passphrase. You can also use the button to generate a new, random passphrase. When you are done, you can save your changes by following the steps below.

    Step 3. Click [OK].

    Figure 4: A modified KeePassXC entry

    Step 4. Click the button to save your password database.

    Note: Remember that making changes to a KeePassXC entry only updates the KeePassXC database. It does not automatically update corresponding information elsewhere. If you change an account or login passphrase, you will need to make changes both to the account and to your KeePassXC entry.

    5. Use the entries in your KeePassXC database

    One of the best features of KeePassXC is that it safely stores long, strong passphrases so you do not have to memorize them (or reuse them, which is extremely risky). KeePassXC lets you copy your passphrases from the database and paste them directly into relevant password or login screens. (Passphrases copied in this way will only remain in your clipboard for about 10 seconds. So if someone with physical access to your device comes along behind you and tries to paste into an empty document, your passphrases will not be exposed.)

    5.1 Sign into an account using KeePassXC

    In this example, we’ll sign into a webmail account by copying and pasting a passphrase from our KeePassXC entry for the Riseup email service.

    Step 1. Browse to the login screen of your service provider.

    Figure 1: A Riseup email login screen

    Step 2. Type your username.

    Note: If you entered a Username for this entry in KeePassXC, you can copy it to the clipboard with the Ctrl-click menu. You can then paste it into the login screen rather than typing it.

    Step 3. Switch to KeePassXC.

    Figure 2: Finding the appropriate entry in your KeePassXC password database

    Step 4. Click the Group to which your entry belongs.

    Step 5. Ctrl-click the appropriate entry and select Copy password.

    Figure 3: Copying a passphrase using the ctrl-click menu

    Step 6. Switch back to the login screen

    Step 7. Ctrl-click in the password box and select Paste.

    Figure 4: Pasting a passphrase into a login screen

    You should see a (hidden) passphrase appear in the Password box.

    Figure 5: Pasting a passphrase into a login screen

    Step 8. Click [Login].

    Figure 6: Successfully signed in using KeePassXC

    Note: Select Never Save or Don't Save to refuse your browser's offer to save the password. We do not recommend saving passwords in your browser.

    Tip: For easier copying, switching between applications and pasting, practice using keyboard shortcuts:

    • Select the Group, Click the entry, press and hold the Command key, then press c to copy your passphrase.
    • Click inside the Password box, Press and hold the Command key, then press v to paste that passphrase.
    • You can use Command-b instead of Command-c to copy a username (instead of a passphrase) from within KeePassXC
    • To switch between open windows quickly, you can Press and hold the Command key, then press the Tab key

    6. Managing your KeePassXC database

    6.1 Lock and close KeePassXC

    Leaving your KeePassXC password database open is a bit like storing your valuables in a vault and forgetting to close the door. Anyone with access to your computer for a few seconds can duplicate everything in it. So, when you're not actively copying and pasting passphrases, you should close your database. You will have to enter your master passphrase next time you need to lookup an entry, but that's a good thing.

    KeePassXC includes a few optional settings designed to make this easier, including the ability to lock your database automatically. Follow the steps below to enable this feature and to practice locking your database in a hurry.

    Step 1. Click Tools and select Settings from the KeePassXC menu bar, as shown below

    Figure 1: Selecting KeePassXC Preferences

    This will activate the Settings screen

    Figure 2: The KeePassXC Settings screen

    Step 2. Click Security from the list of categories on the left

    Figure 3: KeePassXC Security settings

    In this example, we will configure KeePassXC to lock automatically after one minute.

    Figure 4: Configuring KeePassXC to lock automatically

    Step 3. Check the Lock database after inactivity of box

    Step 4. Type a number of seconds in the field to the right

    Tip: You can also change the number of seconds that KeePassXC leaves copied passphrases in the clipboard before deleting them. If the default 10 seconds does not feel like enough, you might want to change the value in Clear clipboard to 20 or 30 seconds.

    Step 5. Click [OK]

    You can also lock your password database manually. Follow the steps below to practice saving and locking your database quickly.

    Step 6. Press Command-s to save your password database. (You can also click the button.)

    Step 7. Press Command-l lock your password database. (You can also click the button.)

    Figure 5: A locked database in KeePassXC

    To open your database again, follow the steps below.

    Figure 6: Opening a locked KeePassXC database

    Step 8. Type your master passphrase into the Password box.

    Step 9. Click [OK].

    6.2 Back up your KeePassXC database

    You should create multiple copies of your password database and try to keep at least one backup that is relatively up-to-date. All of your backup copies will be protected by your master passphrase, so it is generally safe to store them on regular, unencrypted hard drives and USB memory sticks.

    To make a backup copy of your password database, follow the steps below:

    Step 1. Navigate to your password database. Ctrl-click your password database and Select Copy

    Figure 1: Locating your password database and copying it

    Step 2. Navigate to another location. In this example, we use a USB memory stick. Ctrl-click in the location you have chosen and Select Paste.

    Figure 2: Pasting a backup copy of your password database to location for your backup

    Step 3. Ctrl-click the backup copy of your password database and Select Rename.

    Figure 3: Choosing a new name for your backup copy

    Step 4. Type a new name for your backup copy so you don't get it confused with your master copy.

    Step 5. Press Enter.

    Figure 4: A new password database backup

    Tip: KeePassXC does not automatically update all copies of a database when changes are made. You have to do this manually. It’s a good habit to regularly replace backup copies of your KeePassXC database. That way you won’t lose all of your new entries if you misplace your database file.

    6.3. Resetting your master passphrase

    You can change the master passphrase for a KeePassXC database any time. To change your master passphrase, follow the steps below.

    Step 1. Click Database and select Change master key from the KeePassXC menu bar, as shown below:

    Figure 1: Changing your master passphrase

    This will activate the Change Master Key screen.

    Figure 2: Choosing a new master passphrase

    Step 2. Choose a strong passphrase and type it into the Enter password and Repeat password boxes.

    Step 3. Click [OK].

    Step 4. Click the button to save your database.

    6.4 Importing a password database from KeePass or older versions of KeePassXC

    KeePassXC can open a KeePassX password database as long as it was created with a relatively recent version of KeePassX. However, the password database format used in older versions of KeePassX (including version 0.4.3) is no longer maintained. If you have a password database that was created using an old version of KeePassX, or using KeePass, you should import it into KeePassXC and re-save it. To do so, follow the steps below.

    In this example, we will assume that you already have an up-to-date password database open in KeePassXC, but you can also import databases into a fresh installation of KeePassXC.

    Step 1. Click Database and select Import KeePass 1 database, as shown below.

    Figure 1: Importing an older password database

    In this example, we will import a file called "old-database.kdb" located on the Desktop.

    Step 2. Navigate to the location of your older password database.

    Figure 2: Locating your older KeePass password database

    Step 3. Select the password database file.

    Step 4. Click [Open].

    Step 5. Type the master passphrase for your older password database.

    Figure 3: Entering the master passphrase for your older password database

    Step 6. Click [OK].

    Note: If you already have a database open, KeePassXC will open your older database in a second tab

    Figure 4: A second, older password database open in a second tab

    You can save this database normally and it will be converted to the current KeePassXC database format.

    Step 7. To save your older database in the new format Click Database and select Save database as..., as shown below.

    Figure 5: Saving an up-to-date copy of an older password database

    In this example, we are saving our imported password database to the Desktop and naming it "imported-db.kdbx".

    Step 8. Navigate to the location where you would like to store a new copy of this password database.

    Step 9. Type a filename for your new password database into the File name box.

    Figure 6: Choosing a location and a name for your updated password database

    Step 10. Click [Save].

    Your imported database is now up-to-date and should contain all of the entries it had before. You can access and modify it normally using up-to-date versions of KeePassXC and its original master passphrase.

    Note: Don't be confused by the filename displayed in the KeePassX title bar or tab. It will reflect the previous name of this password database, even when you are opening an imported, up-to-date file. (Note the "old-keepassx-db.kdb" in the figure above. In fact, this database is now called "imported-db.kdbx".)


    Q: On the outside chance that I forget my master password, is there anything I can do to access retrieve my saved passphrases?

    A: Nope. There is nothing you can do in that situation. To prevent this from happening, you could use some of the methods for remembering passphrases that are described in the Create and maintain strong passwords guide.

    Q: And if I uninstall or remove KeePassXC, what will happen to my passwords?

    A: The program will be deleted from your computer, but your database (stored in a .kdbx file) will remain. You can open this file at any time in the future if you install KeePassXC again.

    Q: I think I accidentally deleted the database file!

    A: Hopefully you made a backup beforehand. Make sure you haven't simply forgotten where you stored the file in the first place. Search your computer for a file with a .kdbx extension.