# UniProt FASTA Download Not Working? The single most common reason a UniProt FASTA download fails is that the website exports whatever is currently in your result set, and your current result set is not what you think it is. You click Download, the browser saves a file, and the file is empty, truncated, or full of the wrong sequences. Almost every report of a UniProt FASTA download not working traces back to one of these situations, a format mix-up, a query that matched nothing, or a download limit on very large result sets. This guide walks through the causes from most common to rarest, explains the mechanism behind each failure, gives you a short diagnostic sequence you can follow in minutes, and shows the command-line alternatives that bypass the web interface entirely. If you are new to UniProt, a short tutorial on how the database is organized is included so the troubleshooting steps make sense. ## First Thing to Check: Open the File You Already Have Before you retry the download, look at what actually landed on your disk. Most "failed" downloads are intact files that were simply not what you expected. Open the downloaded file in a plain text editor such as Notepad, TextEdit (in plain text mode), VS Code, or nano. A valid FASTA file has this structure: ``` >sp|P04637|P53_HUMAN Cellular tumor antigen p53 OS=Homo sapiens OX=9606 GN=TP53 PE=1 SV=1 MEEPQSDPSIEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP ... ``` Each sequence begins with a header line starting with the greater-than character, followed by the sequence in single-letter amino acid codes. If you see comma-separated columns instead, you downloaded a tab-separated table, not FASTA. If you see nothing at all, your query returned zero entries. If you see headers but they stop partway through, your download was truncated or capped. Count the sequences from the terminal: ```bash grep -c '^>' uniprot_download.fasta ``` This one command answers the question "did I get anything, and how much of it?" faster than any other diagnostic. Compare the count to the number of results UniProt reported above your search results. A mismatch tells you immediately that the problem is scope (how many entries) rather than format (what kind of file). ## Quick Diagnostic Sequence ![Path starting from an empty or short FASTA file, checking header lines, format choice and a single accession, ending in a query fix.](/article-images/illustrations/uniprot-fasta-download-not-working-empty-file-triage.webp) Run through these five checks in order. They resolve the majority of UniProt FASTA download failures. 1. **Check the file contents.** Open it in a text editor. Valid FASTA starts each record with `>`. 2. **Count the headers.** Run `grep -c '^>' filename.fasta` and compare against the result count on the UniProt results page. 3. **Check the format you selected.** On the results page, the Download button offers several formats. FASTA (canonical), FASTA (all isoforms), TSV, XLS, GFF, and others are separate choices. Confirm you picked a FASTA option. 4. **Check your query.** Reproduce the search in the UniProt search bar and read the result count out loud. A query like `BRCA1` without an organism filter matches thousands of entries across species, including unreviewed, automatically annotated records. 5. **Try one known entry directly.** Fetch a single accession you can verify by eye. If a single-entry download works but your search download fails, the problem is your query. If both fail, the problem is your network, tooling, or the service itself. ## Troubleshooting Table This table is the core of the article. Find the symptom that matches what you observe, confirm the cause, then apply the fix. | Symptom | Likely cause | How to confirm | Fix | |--|--|--|--| | File downloads but is completely empty (0 bytes or 0 header lines) | Search query matched zero entries, or you clicked Download before running a search | Re-run the search and read the result count above the table | Correct the query syntax, remove over-restrictive filters, or search by gene name plus organism | | File contains table columns, not sequences | You selected TSV, XLS, or another tabular format instead of FASTA | Open the file, look for tab- or comma-separated fields | Re-download and choose "FASTA (canonical)" from the format list | | FASTA opens in Excel with sequences split across columns or replaced by gibberish | Excel opened the file and mangled or re-saved it | Check whether the file size changed after opening, look for broken headers | Never open raw FASTA in Excel. Use a text editor, or re-download if Excel overwrote the original | | Sequence count is lower than the result count shown on the website | Web interface download cap on large result sets, or the canonical-only option skipped isoforms you expected | Count headers with `grep -c '^>'` and compare to the result count | Use the REST API with pagination or the stream endpoint for large sets, see the command-line section below | | An accession number returns nothing at all | The accession was merged into another entry or deprecated | Search UniProt for the protein name and organism, check whether UniProt reports a merged or deleted entry | Use the replacement accession UniProt reports, or use UniProt's ID mapping service to convert your identifier list | | Downloaded sequences include proteins from the wrong species | Missing organism filter in the query | Look at the `OS=` organism field in each FASTA header | Add `organism_id:` with the correct NCBI taxonomy identifier, for example 9606 for human | | Too many unreviewed, predicted sequences mixed with curated ones | Query did not restrict to reviewed entries | Headers beginning `tr|` are unreviewed TrEMBL entries, `sp|` are reviewed Swiss-Prot entries | Add `reviewed:true` to the query if you want curated entries only | | Browser download stalls, times out, or dies on a huge query | Web browser and server timeouts on very large downloads | The file on disk stops growing or the transfer aborts mid-stream | Download via REST from the command line, which supports long-lived connections and resumable file handling | | Command-line requests return 403 or 429 errors | Rate limiting from too many rapid requests, or a proxy blocking the request | Check whether errors start after you increase request frequency | Add a pause between requests, typically one second, reduce concurrency, and retry with backoff | | Service returns 5xx errors or behaves oddly for everyone | Scheduled maintenance or a service incident | Try a simple query in the browser, ask a colleague to try | Wait and retry, UniProt posts maintenance notices on its site | ## How UniProt Is Organized: A Short Orientation If you are new to UniProt, three distinctions explain most download confusion. **Swiss-Prot versus TrEMBL.** UniProt combines two knowledgebases under one search interface. Swiss-Prot entries are curated by expert biologists, carry the `sp|` prefix in FASTA headers, and are the highest-quality records. TrEMBL entries are computationally annotated, carry the `tr|` prefix, and are not manually reviewed. When you search a common gene name without filters, you usually get both, which is why results contain far more entries than you expected and why two colleagues can download "the same protein" and get different sequences. **Canonical sequence versus isoforms.** One UniProt entry can describe several protein isoforms produced by [alternative splicing](/blog/guides/alternative-splicing). The canonical sequence is the representative one shown by default. A FASTA download of a single entry may therefore produce one record or several, depending on the isoform option you choose and on whether that entry has alternative isoforms at all. **Accessions versus entry names.** Every entry has a stable accession such as P04637 and a mnemonically named entry name such as P53_HUMAN. The accession is the stable identifier you should use in scripts and databases. Entry names can change, accessions do not, but accessions can be merged or retired, which is a separate failure mode covered below. Published workflows lean on this structure heavily. One study of AIM-2 inflammasome peptides downloaded its protein sequences from UniProt in FASTA format at 100%, 90%, and 50% similarity thresholds before training deep learning models on them [1]. That pattern, download once at several redundancy levels, then build datasets from each, is only reproducible if you know exactly which filter settings produced each file. ## Cause 1: Your Query Matched Nothing (Most Common) The web interface downloads the result set currently in view. If your search returns zero entries, the download button produces an empty file without complaint. This is the top cause of an empty UniProt FASTA download. Common query mistakes include these: - **Typos in field names.** [UniProt search fields](/knowledge/bioinformatics/uniprot-search-fields) have exact names. `gene:` works, `gene name:` does not. `organism_id:` takes a numeric taxonomy identifier, not a species name. - **Missing organism restriction.** Searching `gene:TP53` matches TP53 in every annotated species. Restrict with `organism_id:9606` for human, 10090 for mouse, or the taxonomy identifier for your organism. - **Over-restricted combinations.** Chaining many filters with `AND`, such as a specific gene, a specific tissue annotation, and a sequence length range, can eliminate every entry. Build the query one clause at a time and watch the result count after each addition. - **Case and spacing.** UniProt search is generally forgiving of case, but extra spaces inside field values can break matching. A well-formed query looks like this: ``` (gene:BRCA1) AND (organism_id:9606) AND (reviewed:true) ``` That query asks for the BRCA1 gene, in human, in reviewed entries only. If this returns the number of entries you expect, the download will contain them. ## Cause 2: Wrong File Format Selected The Download control on the UniProt results page offers a list of formats. FASTA (canonical) and FASTA (all isoforms) are the two sequence formats. The rest, including TSV, XLS, GFF3, and XML, contain annotation tables or feature coordinates, not amino acid sequences. The failure looks like this: you select a format from the list, the browser saves a file, and later you try to load it into BLAST, a [multiple sequence alignment](/blog/guides/multiple-sequence-alignment) tool, or a script, and the tool rejects it. The file is fine, the format is wrong. There is a related and nastier variant. If a TSV or XLS export is opened in a spreadsheet program and then saved, the spreadsheet can silently alter gene symbols and corrupt the data. This failure mode is well documented for spreadsheet software in general. The fix is discipline rather than technology. Keep raw downloads read-only, and inspect them only in text editors or at the command line. ## Cause 3: Result Set Size Limits and Truncation When a search returns a very large number of entries, the web interface may not download all of them in one click. The symptom is a header count far below the reported result count. The mechanism is straightforward, the website is designed for interactive browsing, not bulk export, and bulk exports of millions of records are served through other channels. The solutions, in order of preference: **For whole proteomes, use the proteome page or stream endpoint.** UniProt assigns each complete proteome an identifier beginning with UP, for example UP000005640 for the human reference proteome. You can stream the full set as FASTA: ```bash curl "https://rest.uniprot.org/uniprotkb/stream?query=(proteome:UP000005640)&format=fasta" -o human_proteome.fasta ``` **For large search results, paginate with the REST API.** The search endpoint returns results in pages and provides a cursor for the next page in its response headers. This loop writes all matching FASTA records to one file: ```bash #!/usr/bin/env bash base='https://rest.uniprot.org/uniprotkb/search' query='(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)' out='brca1_human.fasta' cursor='' touch "$out" while :; do if [ -n "$cursor" ]; then curl -sD h.txt -G "$base" \ --data-urlencode "query=$query" \ --data-urlencode "format=fasta" \ --data-urlencode "size=500" \ --data-urlencode "cursor=$cursor" >> "$out" else curl -sD h.txt -G "$base" \ --data-urlencode "query=$query" \ --data-urlencode "format=fasta" \ --data-urlencode "size=500" >> "$out" fi next=$(grep -io 'cursor=[^">]*' h.txt | head -1 | cut -d= -f2) if [ -z "$next" ]; then break fi cursor="$next" sleep 1 done rm -f h.txt ``` The `sleep 1` between pages keeps request volume reasonable. A verify step afterward confirms you captured everything: ```bash grep -c '^>' brca1_human.fasta ``` **Safety note.** The script above ends with an `rm` command. Before running any script that deletes files, read every line, confirm the filename it targets, and run it in a directory where a mistake cannot destroy other work. This is the same caution you would apply before running any pipeline step that writes or removes data. ## Cause 4: Merged, Deleted, or Changed Accessions ![Flowchart from a failing accession through a direct search, merge notice, ID mapping and UniParc, ending in a replacement accession.](/article-images/illustrations/uniprot-fasta-download-not-working-accession-no-result.webp) You have a list of accession numbers from an old paper or an old supplementary file. Some of them return nothing. The mechanism here is database maintenance over time. When UniProt curators determine that two entries describe the same protein, one accession is merged into the other. When an entry is removed entirely, the accession is retired. The sequences are not lost, they live in UniParc, the UniProt Archive, which stores every unique sequence ever ingested along with cross-references to the more than 70 source databases that contain it [2]. This identifier instability is a known, general problem in protein databases. Each major database assigns identifiers under its own conventions, and the identifiers referring to identical proteins can differ or change across databases and over time, which is precisely the problem the PICR mapping service was built to address by using 100% sequence identity in UniParc to reconcile identifiers across source databases [2]. Practical fixes: - **Let UniProt tell you.** Paste a retired accession into the UniProt search bar. If it was merged, the interface reports the replacement accession. - **Use ID mapping.** UniProt provides an ID mapping tool where you paste a list of identifiers from another database, for example RefSeq or Ensembl identifiers, and receive the corresponding UniProt accessions. This is the correct first step whenever your source list came from a database other than UniProt. - **Do not assume stability across database releases.** If your pipeline depends on a specific accession resolving to a specific sequence, record the sequence itself or its checksum, not just the accession. ## Cause 5: Canonical Versus Isoform Confusion You expected 1 sequence and got 3, or you expected 3 and got 1. The mechanism is alternative splicing. An entry with isoforms produces different numbers of FASTA records depending on your download choice. - **FASTA (canonical)** gives one sequence per entry, the representative sequence. - **FASTA (all isoforms)** gives every isoform described by the entry, each as its own record, with distinct accession-style identifiers in the header. Neither choice is wrong. What breaks pipelines is inconsistency between collaborators. If one person builds a BLAST database from canonical sequences and another from all isoforms, their search results will differ. Decide as a group which option your project uses, write it into the methods, and keep it fixed. The reverse failure also happens. You download with all isoforms, then a downstream tool complains about duplicate or near-duplicate sequences, because isoforms of the same protein share most of their length. Published machine learning workflows handle this by clustering at explicit similarity thresholds before model training, exactly as the AIM-2 inflammasome study did with its 100%, 90%, and 50% similarity sequence sets [1]. Clustering is the standard solution, not a sign that the download failed. ## Cause 6: Reviewed Versus Unreviewed Contamination You wanted 20 curated human proteins and got 400. The mechanism is TrEMBL. Automatic annotation propagates protein records across species, so a search for a gene name without `reviewed:true` matches curated and predicted records alike. Check what you actually downloaded by looking at the first field of each header: - `sp|P04637|P53_HUMAN` means reviewed Swiss-Prot. - `tr|A0A024R161|A0A024R161_HUMAN` means unreviewed TrEMBL. Count each type: ```bash grep -c '^>sp|' uniprot_download.fasta grep -c '^>tr|' uniprot_download.fasta ``` If the ratio surprises you, add `reviewed:true` to the query and re-download. For comparative analyses where curation quality matters, restricting to reviewed entries is standard practice. For maximum recall across poorly studied species, you may deliberately keep TrEMBL entries, but make that choice deliberately, not by accident. ## Cause 7: Network, Proxy, and Tooling Problems If a single-entry download fails in both the browser and at the command line, the problem is between your machine and UniProt. - **Corporate or institutional proxies.** Some proxies block or slow large downloads. Test whether a small file transfers successfully. If small requests work and large ones fail, ask your network administrator about transfer limits. - **Rate limiting.** If your script loops over hundreds of accessions with no pause, the service responds with 403 or 429 errors. Add a pause between requests and retry failed requests with increasing delay. - **User agent blocking.** A few institutional firewalls strip or alter the HTTP user agent. If plain `curl` fails where the browser succeeds, compare the behavior and try `curl` with the browser-like user agent flag only after confirming the block exists. - **Silent proxy environment variables.** In shared computing environments, `http_proxy` and `https_proxy` environment variables may route your requests unexpectedly. Check them with `env | grep -i proxy` if behavior differs between machines. - **Disk space and permissions.** A download that writes zero bytes can simply be a full disk or a directory you cannot write to. Check with `df -h .` and `touch testfile` in the target directory. ## Cause 8: Service Maintenance and Server Errors UniProt, like all major databases, schedules maintenance and occasionally experiences incidents. The signature is that everything works for a colleague or from a different network, or that a query that worked yesterday fails with a 5xx error today. Confirm by trying a trivial request, such as fetching the FASTA for P04637, in a plain browser window. If trivial requests fail on multiple networks, the service itself is the problem. UniProt posts notices about scheduled downtime on its website. There is nothing to fix on your end, so wait and retry rather than rewriting a working script. ## How to Fix UniProt FASTA Download Not Working, Step by Step If you want a single ordered procedure rather than a diagnostic tree, follow this sequence. It moves from the cheapest checks to the most involved. 1. Open the downloaded file in a text editor and count header lines with `grep -c '^>'`. 2. If the count is zero, fix the query. Add an organism filter and, if appropriate, `reviewed:true`. Re-run the search and confirm a nonzero result count before downloading again. 3. If the count is nonzero but the file has no sequences, you downloaded a non-FASTA format. Redownload, choosing FASTA (canonical). 4. If the count is lower than the reported result count, switch to the REST API. For a whole proteome, use the stream endpoint. For a filtered search, use the paginated loop shown above. 5. If specific accessions return nothing, check for merges through the UniProt interface or map your identifiers through the ID mapping tool. 6. If everything fails everywhere, test with `curl` and the smallest possible request. If that also fails on multiple networks, wait for the service to recover. ## Practical UniProt Tutorial: Getting Sequences the Reliable Way This section covers how to use UniProt for the three download tasks that come up most often in real projects, using the REST API, which behaves identically regardless of browser. **Single sequence.** Fetch one entry by accession: ```bash curl "https://rest.uniprot.org/uniprotkb/P04637.fasta" -o p53.fasta head -1 p53.fasta ``` **A list of accessions.** Put one accession per line in `accessions.txt`, then fetch each one. The pause keeps request pressure low: ```bash while read -r acc; do curl -s "https://rest.uniprot.org/uniprotkb/${acc}.fasta" >> batch.fasta sleep 1 done < accessions.txt grep -c '^>' batch.fasta ``` **A filtered search.** Use the search endpoint with your query, as shown in the pagination loop above. The query syntax in the API matches the syntax in the website search bar, so you can perfect the query interactively first and then paste it into the script. **An entire proteome.** Search the proteome identifier, or browse the proteome pages on the UniProt site, which present the proteome with its source and annotation status so you can confirm you are downloading the reference set rather than a redundant or alternative assembly. The search endpoint and the website share the same query language, so whatever you refine interactively translates directly into a script. That single fact is the most useful thing to internalize from any UniProt database tutorial, because it means you never have to debug a query twice, once in the browser and once in code. ## Verifying Your Download Before You Build on It A download that looks successful can still be wrong for your purpose. Verification takes minutes and prevents days of confusion downstream. Sequence analysis tools that consume FASTA input, such as viewers that map mutations onto protein architecture, depend on the sequence being the one you intended, which is why mutation interpretation tools accept both UniProt accessions and FASTA sequences as input and validate the correspondence between them [3]. Verify four things: 1. **Count.** `grep -c '^>' file.fasta` matches your expectation. 2. **Identity.** Spot-check one or two entries. Confirm the gene name and organism in the FASTA header match what you intended. The `OS=` field carries the organism and `OX=` carries the taxonomy identifier. 3. **Length.** For a key protein, check that the sequence length matches the length reported on its UniProt entry page. A mismatch usually means you downloaded an isoform when you wanted the canonical sequence, or vice versa. 4. **Integrity.** Generate a checksum and record it, so you can prove later that the file used for an analysis is the file you think it was: ```bash md5sum brca1_human.fasta ``` Store the checksum alongside the file and note the query string, download date, and UniProt release information in a small README in the same directory. This turns a one-off download into a reproducible dataset. Published pipelines that download UniProt sequences at multiple similarity thresholds depend on exactly this kind of recorded provenance to keep their datasets distinct and their results reproducible [1]. ## Prevention Practices These habits prevent almost every recurrence of a failed UniProt download. - **Write the query down.** Record the exact query string, the result count at download time, and the date. If a collaborator gets a different count six months later, you can tell whether the query or the database changed. - **Prefer the command line for anything you will repeat.** Browser downloads are fine for one-off files. Anything you will redo, rerun, or share belongs in a script. - **Restrict scope explicitly.** Every query should include the organism and review status you intend. Unfiltered queries are the largest source of surprise sequence counts. - **Never open raw FASTA in a spreadsheet.** Use text editors and command-line tools. Keep originals read-only. - **Checksum and archive.** Save the md5sum with each dataset so silent corruption or accidental overwriting is detectable. - **Map identifiers at the start, not the end.** If your identifier list originates outside UniProt, run it through ID mapping before building any downstream analysis, because cross-database identifier reconciliation is a recognized challenge and the mapping tools exist for exactly this purpose [2]. - **Decide canonical versus isoforms once per project.** Document the choice in your methods and apply it everywhere. ## Common Mistakes and Limitations These are the mistakes that appear repeatedly in real projects, along with honest limits of what a download checklist can do. - **Assuming the browser download is complete.** For large result sets, the web interface is not the right tool. If your result count is in the tens of thousands or higher, go straight to the REST API or proteome downloads. - **Confusing zero results with a broken service.** An empty file almost always means an empty result set. Debug the query before blaming the network. - **Mixing Swiss-Prot and TrEMBL unknowingly.** Analyses that assume expert curation break when predicted entries slip in. Check the `sp|` versus `tr|` prefix distribution in every downloaded file. - **Building on accessions alone.** Accessions can merge or retire. If a specific sequence matters to your analysis, keep the sequence itself, not just its identifier. - **Ignoring isoform choices.** Canonical and all-isoform downloads are different datasets. Two team members using different options will produce different alignment and search results and will blame the wrong step. - **Skipping verification.** The four checks in the previous section take minutes. Downstream failures take days. - **A general limitation.** This guide covers the mechanics of obtaining and validating sequence data. Whether a particular protein, isoform, or annotation suits your scientific question requires domain judgment about your experiment, and no download procedure substitutes for that judgment. Individual research cases need expert review of the biological context. ## Frequently Asked Questions ### Why is my UniProt FASTA file empty? Your search query returned zero entries, and the website exported that empty result set. Fix the query by adding a correct organism filter and loosening over-restrictive terms, confirm a nonzero result count on the results page, then download again. ### Why do I get fewer sequences than the search results show? Large result sets can be capped or truncated by the web download, and the canonical-sequence option omits isoforms. Count your headers with `grep -c '^>'`, then switch to the REST API with pagination or the stream endpoint for large sets. ### How do I download FASTA sequences for a list of UniProt accession numbers? Put one accession per line in a text file, loop over it with `curl` requesting `https://rest.uniprot.org/uniprotkb/{accession}.fasta`, append each result to one file, and pause briefly between requests. Finish by counting header lines to confirm you captured every entry. ### What is the difference between canonical and isoform FASTA downloads? Canonical FASTA gives one representative sequence per entry. All-isoform FASTA gives every alternative splice isoform the entry describes, so the same entry can yield several records. Pick one convention per project and document it, because the two files are not interchangeable. ### Can I download an entire proteome, like all human proteins, in one file? Yes. Use the proteome identifier, for example UP000005640 for the human reference proteome, in a stream request such as `curl "https://rest.uniprot.org/uniprotkb/stream?query=(proteome:UP000005640)&format=fasta"`. This is the reliable route for proteome-scale files, which are too large for the browser interface. ### Why does a UniProt accession number return no results? The accession was likely merged into another entry or retired. Search the accession directly and read the merge notice, or run your identifier list through UniProt's ID mapping tool, which reconciles identifiers across source databases using sequence identity in the UniParc archive. ### How do I check whether my FASTA download is correct? Count header lines with `grep -c '^>'`, spot-check gene names and organisms in the headers, confirm one sequence length against its UniProt entry page, and generate an md5sum to detect later corruption. These four checks take minutes and catch nearly every real problem. ### Is there a way to automate UniProt FASTA downloads instead of using the website? Yes. The REST API at rest.uniprot.org serves single entries, paginated search results, and full proteome streams over plain HTTP requests, so `curl`, Python, or R scripts can automate everything the website does, with the same query syntax and no browser involved. ## Sources 1. [Artificial intelligence-powered prediction of AIM-2 inflammasome sequences using transformers and graph attention networks in periodontal inflammation.](https://pubmed.ncbi.nlm.nih.gov/40082687/) 2. [The Protein Identifier Cross-Referencing (PICR) service: reconciling protein identifiers across multiple source databases.](https://pubmed.ncbi.nlm.nih.gov/17945017/) 3. [HPMV: human protein mutation viewer - relating sequence mutations to protein sequence architecture and function changes.](https://pubmed.ncbi.nlm.nih.gov/26503432/)